RogueSpirit said:
Is there a guide anywhere that might help learning what to edit to change the npc's behavior. For example to change a faction or the hostility of NPC's? I know that it can be done by editing the .xml files but I am not clear on which files and if there is an existing list of factions that have to be used or can I create my own.
I wrote a good chunk of the faction-related code that is in SCore, so I can give you the details. I expect a lot of people will have questions about NPCs and factions, so I'll try to answer them here.
This is meant to be kind of a "user's manual" so it's long and detailed. Skip it if you're not interested in modding the factions or NPCs.
1. How are factions and relationships defined in XML?
Each faction, and its relationships with other factions, is defined in npc.xml. There are factions that are defined in vanilla XML, and factions defined by NPC Core XML.
Here is the vanilla XML that defines the "duke" faction:
<faction name="duke">
<relationship name="*" value="neutral"/>
<relationship name="whiteriver" value="dislike"/>
<relationship name="undead" value="hate"/>
<relationship name="bandits" value="dislike"/>
</faction>
Between vanilla and NPC Core, there are a whole lot of factions. But if you want to define your own, that is the XML you would need to write.
2. What factions are already defined?
Vanilla defines these factions:
- "none": for non-player entities that don't specify which faction they belong to (see below)
- "animals": vanilla animals - can't be used for faction targeting
- "undead": zombies
- "bandits": human enemies; "bad guys"
- "whiteriver": Noah's clan (apparently based on the real Whiteriver, AZ); "good guys"
- "duke": the Duke's clan
- "trader": traders
NPC Core defines these additional factions:
- "whisperers": TWD-style whisperers (I just released a pack for these guys, see my thread if you want it)
- "vault": Fallout-style vault dwellers
- "military": military
- "redteam": sample military faction, currently unused
- "blueteam": sample military faction, currently unused
- "blueteam": sample military faction, currently unused
- "mechs": enemy mechs, robots, cyborgs, etc.
- "allymechs": currently unused
NPC Core also created these animal factions, and it sets the factions of vanilla animals to use them:
- "companionanimals": used by the NPC Core fox
- "zombieanimals": bears, vultures, dogs
- "passiveanimalssmall": rabbit, chicken
- "passiveanimalsmedium": stag, doe, boar
- "passiveanimalslarge": not currently used
- "aggressiveanimals": not currently used
- "aggressiveanimalssmall": snake, coyote
- "aggressiveanimalsmedium": wolf, dire wolf, mountain lion
- "aggressiveanimalslarge": bear, Grace
3. What do the relationship values mean?
In the XML, the "relationship" tag defines a relationship between the faction and another faction. The "name" property specifies the other faction.
The special value "*" means "any other faction that isn't defined here." That includes all player characters. (It does not include members of the same faction.)
In 7D2D, the relationships between factions are stored as numbers between 0 and 1000 (inclusive). The values in XML specify the tier of the relationship.
Here are the values for each tier:
- "hate": 0
- "dislike": 200
- "neutral": 400
- "like": 600
- "love": 800
The relationship between members of the same faction is always "love". (TFP hard-coded this.)
A relationship of "hate" means that the NPC will attack the member of the other faction (or player) on sight. Otherwise, the NPC will not attack the other NPC/player, unless that other NPC/player damages them first.
The faction relationship also determines "friendly fire" rules. If a the relationship with the other entity is high enough, the NPC can't damage that other entity. Note that the "other entity" could be any entity, including the player.
- If the NPC descends from the C# EntityNPC class, the relationship needs to be "neutral" or higher to be damage immune.
- If the NPC descends from any other C# class, the relationship needs to be "love" or higher to be damage immune.
- Regardless of C# class, if the other entity is a player, the relationship needs to be "hate" for the player to be damaged.
However, if an NPC is damaged by another entity, that other entity becomes their "revenge target" (this is actually what TFP calls it). Regardless of the above rules, an NPC can damage its revenge target. (An NPC can only have one revenge target.)
The "friendly fire" relationship level can be changed by setting the "DamageRelationship" cvar on the entity class. For instance, to make the player able to damage any NPC, set a cvar when the player spawns in:
<effect_group name="Damage All NPCs">
<triggered_effect trigger="onSelfFirstSpawn" action="ModifyCVar" cvar="DamageRelationship" operation="set" value="1001" />
<triggered_effect trigger="onSelfEnteredGame" action="ModifyCVar" cvar="DamageRelationship" operation="set" value="1001" />
<triggered_effect trigger="onSelfRespawn" action="ModifyCVar" cvar="DamageRelationship" operation="set" value="1001" />
</effect_group>
(This XML is in the NPC Core entityclasses.xml file but is commented out.)
If you want this to apply to NPCs, then you would have to set that cvar on the XML entity class that defines those NPCs. All characters that use NPC Core descend from the "npcMeleeTemplate" entity class, so if you want it to be set on all NPCs (human or otherwise), you could use that.
The exception to all of the above is
the vanilla "animals" faction. SCore is hard-coded such that enemy entities which are part of that faction, totally ignore all faction-based rules. (This was done to fix a bug where the mere presence of SCore, with or without NPC Core, would make all animals immune from damage. It's probably not necessary now that we use tags - see below - but it's still in the code AFAIK.)
3. Which entities use factions? How can you change that?
Please note something important: The entity does
not have to use Utility AI (UAI, used by human NPCs in Core) in order to use faction targeting/friendly fire rules.
An entity's faction is defined by the "Faction" property in its entity class XML (in the entityclasses.xml file). That property is inherited. All vanilla and NPC Core entities have their factions set already.
That doesn't apply to players. Each player is assigned its own unique faction. (So, NPCs have unique relationships with each player in a multi-player game.) Player faction relationships can't be specified in XML, and I'm pretty sure the game would ignore the "Faction" property if you tried to set it on a player's entity class.
However, the mere presence of the "Faction" property doesn't
necessarily mean the faction is actually used by the entity.
SCore has a "config feature block" which is used to configure various things, including NPC behavior. If you want
all entities in the game to use faction targeting/damage rules, you can set the "AllEntitiesUseFactionTargeting" property value to "true".
It is set to "true" in NPC core, so this is the default.
If you only want certain entities to use factions, then you should set that value to "false":
<set xpath="/blocks/block[@name='ConfigFeatureBlock']/property[@class='AdvancedNPCFeatures']/property[@name='AllEntitiesUseFactionTargeting']/@value">false</set>
You can then specify which entities use factions, according to the
tags on the entity (in its "Tags" property in the entity class XML). Note that tags are
not inherited.
In the SCore config feature block, the "UseFactionsTags" property defines which entity tags use faction targeting. To change it, you could edit that by hand, or you could use XPath in your own modlet.
For example, this is what I did in my Whisperers pack, so that zombies don't attack whisperers, and vice versa:
<append xpath="//block[@name='ConfigFeatureBlock']/property[@class='AdvancedNPCFeatures']/property[@name='UseFactionsTags']/@value">,zombie</append>
Another approach is to add one of the existing SCore tags to whichever entity you want to obey faction rules.
These are the entity tags that SCore currently uses to determine whether the entity uses factions:
- human
- bandit
- survivor
- npc
- trader
4. What about follower (hired) NPCs?
Followers (like hired NPCs) always use the faction rules of their
leader (like the player that employs them) for targeting and damage.
The exception is when they are hired by one player, and are targeting another. In this case, they use the same "friendly fire" rules as the players themselves. So, if two players cannot damage each other, then one player's hires can't damage the other player, and one player's hires can't damage the other player's hires.
In either case, the follower's faction is no longer relevant. All of this is hard-coded in SCore and can't be changed.
5. Are faction changes save-game safe?
Absolutely not. You must start a new game if you ever add factions to, or remove factions from, the game.
Here's why. 7D2D saves the factions in an array (with a numeric index), not by name. Let's say you add a new faction. In the game save, the faction at index 10 might have previously belonged to a player, but now belongs to the new faction you just added. It will be a mess - and is hard to debug, because it might not even result in a red error in the console. So, just don't do it.
Hope that helps!
