aka when to use agent vs Moth

agent always refers to the blueprint instance.

Most scripts run in the context of the agent they were defined in (except for when scripts, see below). In these cases, the use of agent is implied, but you can still elect to use it for clarity if you want.

e.g. the following operate the same way

Here's where things get tricky. Even in a when block, agent still refers to the blueprint instance. For example, this is a Predator script, but the when block is referencing Moth and TreeFoliage. Because this is a Predator script, the setGlow on agent is applied to the Predator.

# BLUEPRINT Predator
when Moth lastTouches TreeFoliage [[
  featProp agent.Costume setGlow 0.1
]]

when scripts operate differently, running in a special context. In a when script the agent that is specified in the when statement is passed as context to the code block.

If the when statement references a single agent, the agent context is passed to the code. So in this case the prop Moth.Costume reference refers to the Moth that died.

when Moth dies [[
  featProp Moth.AgentWidgets text setTo 'dead'
]]

If the when statement references two agents, you'll always want to explicitly refer to the agent.

when Predator touches Moth [[
  featProp Moth.AgentWidgets text setTo 'dead'
  prop Predator.energyLevel add 10
]]

agent in a when script always refers to the blueprint instance the script is defined in.

Spawn Scripts are passed the context of the newly spawned agent. They are essentially the same as the SETUP (Map Editor) init scripts

For example, here the populateBySpawning call is in Predator, but the spawn script is passed the context of the newly spawned moth.

# BLUEPRINT Predator
featCall Population populateBySpawning Moth [[
  featProp AgentWidgets text setTo 'Me Moth'
]]

Here you wouldn't want to reference featProp Moth.AgentWidgets... because Moth is not being passed.