View source for Struct: Agent Characteristics

[[Category:Arco_Structs]]
[[Category:Agents/Whiskers]]
{{Arco_Struct_Infobox
 | name    = Agent Characteristics
 | path    = /Script/ProjectArco.AgentCharacteristics
 | purpose = Defines movement, productivity, traits, guild, and appearance for Agents.
 | usedin  = [[Function: Set New Map Starting Agents]]
 | category= [[:Category:Agents/Whiskers]]
}}

= Struct: Agent Characteristics =
''Struct: Agent Characteristics'' is a core data structure in the '''Project Arco''' framework (used internally by '''Whiskerwood''').  
It defines all initialization parameters required to create and configure an NPC Agent, including movement, productivity, traits, guild affiliation, appearance, and various behavioral modifiers.

This struct is used when:
* Generating starting agents for new maps
* Spawning new villagers or migrants
* Applying traits and appearance
* Initializing agent data during world loading
* Creating custom agents via modding

The struct appears in Blueprints as the node: '''Make Agent Characteristics'''.

__TOC__

== Overview ==
''Struct: Agent Characteristics'' acts as a blueprint for an NPC.  
The struct does not represent an agent itself, but instead defines the properties the Arco Framework uses when creating one.  
When passed to functions such as [[Function: Set New Map Starting Agents]], the system constructs:
* Movement values  
* Productivity and work capability  
* Appearance settings  
* Trait sets  
* Guild/education status  
* Behavior modifiers  
* Identity fields (name, portrait)

== Structure Definition ==
The struct is defined under:
<pre>/Script/ProjectArco.AgentCharacteristics</pre>

It contains the fields listed below.  
All fields shown here are derived directly from Blueprint-reflected data.

== Fields ==
=== Movement ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>speedAt100Percent</code> || float || Movement speed when efficiency is 100%.
|-
| <code>base_speed</code> || float || Baseline walk speed before modifiers.
|-
| <code>turnSpeed</code> || float || How fast the agent rotates (degrees/second).
|-
| <code>agentScale</code> || Vector || Scale multiplier for agent’s mesh (default is 1,1,1).
|}

=== Work & Productivity ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>base_productivity</code> || float || Base crafting/work efficiency.
|-
| <code>baseCarryCapacity</code> || int || Maximum items agent can carry.
|}

=== Spawn / Initialization ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>spawnDelay</code> || float || Delay before the agent appears after queued to spawn.
|-
| <code>arrivalCost</code> || int || Cost associated with agent recruitment/arrival.
|}

=== Traits, Guild, Education ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>traits</code> || Set&lt;name&gt; || List of assigned trait IDs (from the Trait Lookup Table).
|-
| <code>education</code> || EAgentEducation || Education tier affecting job eligibility.
|-
| <code>guild</code> || name || Current guild or faction.
|-
| <code>GuildProgress</code> || float || Current experience within assigned guild.
|-
| <code>GuildTarget</code> || name || Rank, specialization, or next objective within guild.
|}

=== Appearance ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>skinColor</code> || Color || Appearance tint / fur color.
|-
| <code>Portrait</code> || name || ID of portrait asset to use in UI displays.
|-
| <code>agentName</code> || string || Display name. Leave empty for auto-generation.
|}

=== Behavioral Modifiers ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>ignoreTerrainDebuffs</code> || bool || If true, agent ignores movement penalties on bad terrain.
|-
| <code>ignoreFarmFieldDebuffs</code> || bool || If true, agent avoids farm-work slowdowns.
|-
| <code>travelVarianceOffset</code> || Vector || Offset used for natural wandering behavior.
|}

=== Expectations ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>expectationExcess</code> || Map&lt;EExpectationType, float&gt; || Modifiers for individual expectation categories (food, comfort, housing, etc.).
|}

=== Progression ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>CraftsmanProgress</code> || float || XP in crafting-type professions.
|-
| <code>ScholarProgress</code> || float || XP in academic/knowledge professions.
|}

=== Identity ===
{| class="wikitable"
! Field !! Type !! Description
|-
| <code>ID</code> || int || Unique agent identifier. Leave 0 or -1 to auto-generate.
|}

== Usage in Blueprints ==
In Blueprints, the struct is created via:
<pre>Make Agent Characteristics</pre>

Once constructed, these structs are typically collected into an array and passed to functions such as:
* [[Function: Set New Map Starting Agents]]

This allows the Arco Framework to register and later initialize the starting population of Agents for a new map or game state.

== Modding Tips ==
* Use <code>traits</code> to grant custom or modded traits.
* Increase <code>base_speed</code> and <code>speedAt100Percent</code> for faster NPCs.
* Set <code>ignoreTerrainDebuffs</code> to create “super workers.”
* Adjust <code>baseCarryCapacity</code> to improve hauling efficiency.
* Leave <code>ID</code> empty unless loading an existing saved agent.
* Customize <code>skinColor</code> and <code>Portrait</code> for unique villagers.
* Guild and education progress values influence job eligibility and skill trees.

== Example Blueprint Initialization ==
<pre>
Make Agent Characteristics
 ├ speedAt100Percent = 400
 ├ base_speed = 250
 ├ base_productivity = 1.5
 ├ traits = { "rude", "swift" }
 ├ skinColor = (R=0.9,G=0.8,B=0.7)
 ├ agentName = "Marlo"
 └ guild = "Farmers"
</pre>

== Related ==
* [[Function: Set New Map Starting Agents]]
* [[Arco Game Instance]]


{{Arco_Structs_Modding}}