T4 Modules Howto Guide/Factions

Factions: Taking Sides!

Factions seem reasonably simple.

In your load.lua file include the following line near the top:

local Faction = require "engine.Faction"

Two default factions are already included, so there is no need to create them:

-- Add a few default factions
_M:add{ name="Players", reaction={enemies=-100} }
_M:add{ name="Enemies", reaction={players=-100} }

engine/Actor.lua includes this line in all actor's init that sets the default faction to enemies:

self.faction = t.faction or "enemies"

At the time of writing ToME's load.lua also includes two additional custom factions:

-- Factions
Faction:add{ name="water lair", reaction={} }
Faction:add{ name="assassin lair", reaction={} }

Without initializing the reaction list, their reaction will be 0 to everyone, aka neutral. This is so they start out neutral, and their reaction to the different sides can change depending on in-game actions. In-game the reactions are modified using the following code:

Faction:setFactionReaction("assassin-lair", "players", -100, true)

Now the assassin lair and players factions hate each other (notice the true, which means the feeling is mutual). The setFactionReaction function uses the faction short names, which are either set explicity in the Faction:add function or are the lowercase version of the faction name with all spaces replaces with "-"s. The above code will only work when in-game, though, and that means not in load.lua. To modify reactions in load.lua you can use the Faction:setInitialReaction function with the exact same parameters as Faction:setFactionReaction.

To make use of custom factions, the actor's faction variable need to be set to the desired faction. For naturally faction creatures this can be set in the NPC definition. For summoned creatures this is set in the talent's code when summoning and creating the creature(setting it to faction "players"). Custom Actor generators may also make use of this.

In order to test for reaction, whether an Actor should be hostile to another, you can use the reactionToward() method.

self:reactionToward(target)

For traps, you can set it so they only trigger against Actors hostile to themselves. For instance, this is a modification of the ToME base elemental trap:

newEntity{ define_as = "TRAP_ELEMENTAL",
    type = "elemental", id_by_type=true, unided_name = "trap",
    display = '^',
    triggered = function(self, x, y, who)
        if who:reactionToward(self) < 0 then
            self:project({type="hit",x=x,y=y}, x, y, self.damtype, self.dam, self.particles and {type=self.particles})
            return true
        else
            return false
        end
    end,
}

If you have multiple factions that players can belong to, make sure to set the faction on the player as late as possible in the descriptor tree [That is, if you had "race", "subrace", and "class" in that order, you'd want to set it at "class"]. You will also want to put the statement in a copy block, as earlier copy blocks (like that used by the default faction) will over-ride later options that aren't.

copy = {
    faction = "yourfactionhere"
}

Go back to T4 Modules Howto Guide