Naev

Module faction

Lua bindings to deal with factions.

Use like: 

 f = faction.get( "Empire" )
 if f:playerStanding() < 0 then
    -- player is hostile to "Empire"
 end

Functions

exists (name) Gets a faction if it exists.
get (name) Gets the faction based on its name.
getAll () Gets all the factions.
player () Gets the player's faction.
__eq (f, comp) __eq (equality) metamethod for factions.
name (f) Gets the faction's translated short name.
nameRaw (f) Gets the faction's raw / "real" (untranslated, internal) name.
longname (f) Gets the faction's translated long name.
areEnemies (f, e[, sys]) Checks to see if f is an enemy of e.
areAllies (f, a[, sys]) Checks to see if f is an ally of a.
hit (f, mod, Whether[, reason="script"[, single=false]]) Modifies the player's standing with the faction.
hit (f, mod, Whether[, reason="script"]) Simulates modifying the player's standing with a faction and computes how much would be changed.
reputationGlobal (f) Gets the player's global reputation with the faction.
reputationText (f[, val=f:reputationGlobal()]) Gets the human readable standing text correpsonding (translated).
reputationDefault (f) Gets the player's default reputation with the faction.
setReputationGlobal (f) Overrides the player's faction global standing with a faction.
applyLocalThreshold (f, sys) Enforces the local threshold of a faction starting at a particular system.
modPlayer (f, mod[, reason="script"]) Modifies the player's standing with the faction.
modPlayerSingle (f, mod[, reason="script"]) Modifies the player's standing with the faction.
modPlayerRaw (f, mod) Modifies the player's standing with the faction.
setPlayerStanding (f, value) Sets the player's standing with the faction.
playerStanding (f, value) Gets the player's standing with the faction.
playerStandingDefault (f) Gets the player's default standing with the faction.
enemies (f) Gets the enemies of the faction.
allies (f) Gets the allies of the faction.
usesHiddenJumps (f) Gets whether or not a faction uses hidden jumps.
logo (f) Gets the faction logo.
colour (f) Gets the faction colour.
known (f) Checks to see if a faction is known by the player.
setKnown (f[, b=false]) Sets a faction's known state.
invisible (f) Checks to see if a faction is invisible the player.
static (f) Checks to see if a faction has a static standing with the player.
reputationOverride (f) Gets the overriden reputation value of a faction.
setReputationOverride (f, Sets) Gets the overriden reputation value of a faction.
tags ([tag=nil]) Gets the tags a faction has.
dynAdd (base, name[, display[, params]]) Adds a faction dynamically.
dynAlly (fac, ally[, remove=false]) Adds or removes allies to a faction.
dynEnemy (fac, enemy[, remove=false]) Adds or removes enemies to a faction.


Functions

exists (name)
Gets a faction if it exists.

Parameters:

  • name string Name of the faction to get if exists.

Returns:

    Faction The faction matching name or nil if not matched.

Usage:

    f = faction.exists( "Empire" )
get (name)
Gets the faction based on its name.

Parameters:

  • name string Name of the faction to get.

Returns:

    Faction The faction matching name.

Usage:

    f = faction.get( "Empire" )
getAll ()
Gets all the factions.

Returns:

    {Faction,...} An ordered table containing all of the factions.
player ()
Gets the player's faction.

Returns:

    Faction The player's faction.

Usage:

    pf = faction.player()
__eq (f, comp)
__eq (equality) metamethod for factions.

You can use the '==' operator within Lua to compare factions with this.

Parameters:

  • f Faction Faction comparing.
  • comp Faction faction to compare against.

Returns:

    boolean true if both factions are the same.

Usage:

    if f == faction.get( "Dvaered" ) then
name (f)
Gets the faction's translated short name.

This translated name should be used for display purposes (e.g. messages) where the shorter version of the faction's display name should be used. It cannot be used as an identifier for the faction; for that, use faction.nameRaw() instead.

Parameters:

  • f Faction The faction to get the name of.

Returns:

    string The name of the faction.

Usage:

    shortname = f:name()
nameRaw (f)
Gets the faction's raw / "real" (untranslated, internal) name.

This untranslated name should be used for identification purposes (e.g. can be passed to faction.get()). It should not be used for display purposes; for that, use faction.name() or faction.longname() instead.

Parameters:

  • f Faction The faction to get the name of.

Returns:

    string The name of the faction.

Usage:

    name = f:nameRaw()
longname (f)
Gets the faction's translated long name.

This translated name should be used for display purposes (e.g. messages) where the longer version of the faction's display name should be used. It cannot be used as an identifier for the faction; for that, use faction.nameRaw() instead.

Parameters:

  • f Faction Faction to get long name of.

Returns:

    string The long name of the faction (translated).

Usage:

    longname = f:longname()
areEnemies (f, e[, sys])
Checks to see if f is an enemy of e.

Parameters:

  • f Faction Faction to check against.
  • e Faction Faction to check if is an enemy.
  • sys System System to check to see if they are enemies in. Mainly for when comparing to the player's faction. (optional)

Returns:

    string true if they are enemies, false if they aren't.

Usage:

    if f:areEnemies( faction.get( "Dvaered" ) ) then
areAllies (f, a[, sys])
Checks to see if f is an ally of a.

Parameters:

  • f Faction Faction to check against.
  • a faction Faction to check if is an enemy.
  • sys System System to check to see if they are allies in. Mainly for when comparing to the player's faction. (optional)

Returns:

    boolean true if they are enemies, false if they aren't.

Usage:

    if f:areAllies( faction.get( "Pirate" ) ) then
hit (f, mod, Whether[, reason="script"[, single=false]])
Modifies the player's standing with the faction.

Also can modify the standing with allies and enemies of the faction.

Parameters:

  • f Faction Faction to modify player's standing with.
  • mod number Amount of reputation to change.
  • Whether System or nil to make the faction hit local at a system, or global affecting all systems of the faction.
  • reason string Reason behind it. This is passed as a string to the faction "hit" function. The engine can generate "kill" and "distress" sources. For missions the default is "script". (default "script")
  • single boolean Whether or not the hit should affect allies/enemies of the faction getting a hit. (default false)

Returns:

    How much the reputation was actually changed after Lua script was run.

Usage:

  • f:hit( -5, system.cur() ) -- Lowers faction by 5 at the current system

  • f:hit( 10 ) -- Globally increases faction by 10

  • f:hit( 10, nil, nil, true ) -- Globally increases faction by 10, but
doesn't affect allies nor enemies of the faction.
hit (f, mod, Whether[, reason="script"])
Simulates modifying the player's standing with a faction and computes how much would be changed.

Parameters:

  • f Faction Faction to simulate player's standing with.
  • mod number Amount of reputation to simulate change.
  • Whether System or nil to make the faction hit local at a system, or global.
  • reason string Reason behind it. This is passed as a string to the faction "hit" function. The engine can generate "kill" and "distress" sources. For missions the default is "script". (default "script")

Returns:

    How much the reputation was actually changed after Lua script was run.
reputationGlobal (f)
Gets the player's global reputation with the faction.

Parameters:

  • f Faction Faction to get player's standing with.

Returns:

    number The value of the standing.

Usage:

    if f:reputationGlobal() >= 0 then -- Player is not hostile
reputationText (f[, val=f:reputationGlobal()])
Gets the human readable standing text correpsonding (translated).

Parameters:

  • f faction Faction to get standing text from.
  • val number or nil Value to get the standing text of, or nil to use the global faction standing. (default f:reputationGlobal())

Returns:

    string Translated text corresponding to the faction value.
reputationDefault (f)
Gets the player's default reputation with the faction.

Parameters:

  • f Faction Faction to get player's default standing with.

Returns:

    number The value of the standing.
setReputationGlobal (f)
Overrides the player's faction global standing with a faction. Use sparingly as it overrites local standings.

Parameters:

  • f Faction Faction to set the player's golbal reptation with.

Returns:

    number The value of the reputation to set to.
applyLocalThreshold (f, sys)
Enforces the local threshold of a faction starting at a particular system. Meant to be used when computing faction hits from the faction standing Lua scripts. Not meant for use elsewhere.

Parameters:

  • f Faction Faction to apply local thresholding to.
  • sys System System to compute the thresholding from. This will be the reference and will not have its value modified.
modPlayer (f, mod[, reason="script"])
Modifies the player's standing with the faction.

Also modifies standing with allies and enemies of the faction.

Parameters:

  • f Faction Faction to modify player's standing with.
  • mod number The modifier to modify faction by.
  • reason string Reason behind it. This is passed as a string to the faction "hit" function. The engine can generate "kill" and "distress" sources. For missions the default is "script". (default "script")

Usage:

    f:modPlayer( -5 ) -- Lowers faction by 5
modPlayerSingle (f, mod[, reason="script"])
Modifies the player's standing with the faction.

Does not affect other faction standings.

Parameters:

  • f Faction Faction to modify player's standing with.
  • mod number The modifier to modify faction by.
  • reason string Reason behind it. This is passed as a string to the faction "hit" function. The engine can generate "kill" and "distress" sources. For missions the default is "script". (default "script")

Usage:

    f:modPlayerSingle( 10 )
modPlayerRaw (f, mod)
Modifies the player's standing with the faction.

Does not affect other faction standings and is not processed by the faction Lua script, so it indicates exactly the amount to be changed.

Parameters:

  • f Faction Faction to modify player's standing with.
  • mod number The modifier to modify faction by.

Usage:

    f:modPlayerRaw( 10 )
setPlayerStanding (f, value)
Sets the player's standing with the faction.

Parameters:

  • f Faction Faction to set the player's standing for.
  • value number Value to set the player's standing to (from -100 to 100).

Usage:

    f:setPlayerStanding(70) -- Make player an ally
playerStanding (f, value)
Gets the player's standing with the faction.

Parameters:

  • f Faction Faction to get player's standing with.
  • value number Faction standing value to get string of.

Returns:

  1. number The value of the standing and the human readable string.
  2. string The text corresponding to the standing (translated).

Usage:

  • if f:playerStanding() > 70 then -- Player is an ally

  • _v, str = f:playerStanding(50) -- Get the standing text for a value of
50
playerStandingDefault (f)
Gets the player's default standing with the faction.

Parameters:

  • f Faction Faction to get player's default standing with.

Returns:

    number The value of the standing.
enemies (f)
Gets the enemies of the faction.

Parameters:

  • f Faction Faction to get enemies of.

Returns:

    {Faction,...} A table containing the enemies of the faction.

Usage:

    for k,v in pairs(f:enemies()) do -- Iterates over enemies
allies (f)
Gets the allies of the faction.

Parameters:

  • f Faction Faction to get allies of.

Returns:

    {Faction,...} A table containing the allies of the faction.

Usage:

    for k,v in pairs(f:allies()) do -- Iterate over faction allies
usesHiddenJumps (f)
Gets whether or not a faction uses hidden jumps.

Parameters:

  • f Faction Faction to get whether or not they use hidden jumps.

Returns:

    boolean true if the faction uses hidden jumps, false otherwise.
logo (f)
Gets the faction logo.

Parameters:

  • f Faction Faction to get logo from.

Returns:

    Tex The faction logo or nil if not applicable.
colour (f)
Gets the faction colour.

Parameters:

  • f Faction Faction to get colour from.

Returns:

    Colour or nil The faction colour or nil if not applicable.
known (f)
Checks to see if a faction is known by the player.

Parameters:

  • f Faction Faction to check if the player knows.

Returns:

    boolean true if the player knows the faction.

Usage:

    b = f:known()
setKnown (f[, b=false])
Sets a faction's known state.

Parameters:

  • f Faction Faction to set known.
  • b boolean Whether or not to set as known. (default false)

Usage:

    f:setKnown( false ) -- Makes faction unknown.
invisible (f)
Checks to see if a faction is invisible the player.

Parameters:

  • f Faction Faction to check if is invisible to the player.

Returns:

    boolean true if the faction is invisible to the player.

Usage:

    b = f:invisible()
static (f)
Checks to see if a faction has a static standing with the player.

Parameters:

  • f Faction Faction to check if has a static standing to the player.

Returns:

    boolean true if the faction is static to the player.

Usage:

    b = f:static()
reputationOverride (f)
Gets the overriden reputation value of a faction.

Parameters:

  • f Faction Faction to get whether or not the reputation is overriden and the value.

Returns:

    number or nil The override reputation value or nil if not overriden.
setReputationOverride (f, Sets)
Gets the overriden reputation value of a faction.

Parameters:

  • f Faction Faction to enable/disable reputation override of.
  • Sets number or nil the faction reputation override to the value if a number, or disables it if nil.
tags ([tag=nil])
Gets the tags a faction has.

Parameters:

  • tag string Tag to check if exists. (default nil)

Returns:

    table or boolean Table of tags where the name is the key and true is the value or a boolean value if a string is passed as the second parameter indicating whether or not the specified tag exists.

Usage:

  • for k,v in ipairs(f:tags()) do ... end

  • if f:tags().likes_cheese then ... end

  • if f:tags("generic") then ... end
dynAdd (base, name[, display[, params]])
Adds a faction dynamically. Note that if the faction already exists as a dynamic faction, the existing one is returned.

Note Defaults to known.

Parameters:

  • base Faction or nil Faction to base it off of or nil for new faction.
  • name string Name to give the faction.
  • display string Display name to give the faction. (optional)
  • params table Table of parameters. Options include "ai" (string) to set the AI to use, "clear_allies" (boolean) to clear all allies, "clear_enemies" (boolean) to clear all enemies, "player" (number) to set the default player standing, "colour" (string|colour) which represents the factional colours. (optional)
dynAlly (fac, ally[, remove=false])
Adds or removes allies to a faction. Only works with dynamic factions.

Parameters:

  • fac Faction Faction to add ally to.
  • ally Faction Faction to add as an ally.
  • remove boolean Whether or not to remove the ally from the faction instead of adding it. (default false)
dynEnemy (fac, enemy[, remove=false])
Adds or removes enemies to a faction. Only works with dynamic factions.

Parameters:

  • fac Faction Faction to add enemy to.
  • enemy Faction Faction to add as an enemy.
  • remove boolean Whether or not to remove the enemy from the faction instead of adding it. (default false)
generated by LDoc 1.5.0 Last updated 2024-11-21 07:14:26