eagle0/docs/BEAST_EFFECTS.md

Adding Beast-Type-Specific Effects

When a province has a BeastsEvent, ProvinceBeastsController spawns a visual effect at the province centroid. By default this is the generic BeastsEffect (circling vultures/crows). Beast-specific effects can override this based on BeastInfo.SingularName.

Architecture

ProvinceBeastsController
  ├── GetBeastName(province) → reads BeastsEvent.BeastInfo.SingularName
  ├── GetEffectPrefab(beastName) → switch on name → returns prefab
  └── SpawnBeastsEffect(provinceId, beastName) → instantiates at centroid

Key files:

File	Purpose
Assets/Eagle/ProvinceBeastsController.cs	Routes beast names to prefabs, positions effects
Assets/Eagle/BeastsEffect.cs	Generic effect (circling birds via particle system)
Assets/Eagle/DragonEffect.cs	Dragon-specific effect (3D model with flying/ground modes)
Assets/Eagle/MonsterEffect.cs	Wandering 2D monster group (DungeonMonsters2D prefabs)
Assets/Eagle/AnimalEffect.cs	Wandering 3D animal group (Animal Pack Deluxe prefabs)
Assets/Eagle/Effects/	All effect prefabs

Adding a new beast type

1. Create the effect MonoBehaviour (or reuse an existing one)

Three effect scripts exist for different asset types:

MonsterEffect (2D sprites, DungeonMonsters2D): Spawns a group of wandering 2D monsters. Uses PascalCase animator states (Idle, Move) and triggers (AttackTrigger, SpecialATrigger). Flips sprite X scale for facing direction. Best for DungeonMonsters2D prefabs.

AnimalEffect (3D models, Animal Pack Deluxe): Spawns a group of wandering 3D animals. Uses lowercase animator states (idle, walk, eat, attack) with Animator.Play(). Rotates model on Y axis for facing. Sets sortingOrder=103, renderQueue=4000, and ZTest=Always to render above the map. Best for Animal Pack Deluxe prefabs.

DragonEffect (single animated 3D creature): Spawns a 3D dragon that alternates between flying (circling at altitude with fly actions) and grounded (wandering with ground actions) modes. Uses Animator.Play() with DragonMapAnims controller. Best for large creatures with flight capabilities.

Particle-based (like BeastsEffect.cs): Good for simple effects like swarms or atmospheric particles.

To create a new effect script, use [RequireComponent(typeof(RectTransform))] for UI canvas positioning and accept tuning parameters as public fields.

2. Create the prefab

1. Create an empty GameObject in Assets/Eagle/Effects/
2. Add a RectTransform component
3. Add your effect MonoBehaviour
4. Wire up any references (animated prefab, textures, materials)
5. Save as prefab

3. Register in ProvinceBeastsController

Add a prefab field and a case in GetEffectPrefab():

// In ProvinceBeastsController.cs

// Add inspector field alongside existing ones:
public GameObject wolfEffectPrefab;

// Add case in GetEffectPrefab(), keyed by singularName from beasts.tsv:
private GameObject GetEffectPrefab(string beastName) {
    switch (beastName) {
        case "dragon": return dragonEffectPrefab;
        case "wolf": return wolfEffectPrefab;
        default: return beastsEffectPrefab;
    }
}

4. Wire up in the scene

In Gameplay.unity, find the ProvinceBeastsController component and assign your new prefab to the new field.

5. Test

Use [ContextMenu] methods on ProvinceBeastsController to test:

• "Test Dragon in Motcia (ID 2)" spawns a dragon effect
• Add similar methods for your beast type
• "Clear All Effects" removes all active effects

Beast name matching

Beast names come from BeastInfo.SingularName in the proto, which uses the canonical singularName from src/main/resources/net/eagle0/eagle/beasts.tsv. The switch in GetEffectPrefab uses exact string matching on this canonical name (e.g. "dragon", "wolf", "skeleton").

Human-type beasts (pirates, bandits, etc.) are matched via a HumanBeastNames HashSet in ProvinceBeastsController rather than individual switch cases.

Beast animation coverage

Custom animations

Beast	Effect Type	Asset Pack	Prefabs Used
dragon	DragonEffect	3dFoin Dragon	dragon_skin.FBX (w/ DragonMapAnims controller)
skeleton	MonsterEffect	DungeonMonsters2D	SkeletonWarrior, SkeletonArcher, SkeletonMage
zombie	MonsterEffect	DungeonMonsters2D	Zombie, ZombieWarrior
rat	MonsterEffect + AnimalEffect	DungeonMonsters2D + Animal Pack Deluxe	Rat (2D), Rat (3D)
spider	MonsterEffect	DungeonMonsters2D	Spider
demon	MonsterEffect	DungeonMonsters2D	Demon, Succubus
orc	MonsterEffect	DungeonMonsters2D	Imp
vampire	MonsterEffect	DungeonMonsters2D	Vampire
knight types (6 names)	AnimalEffect	Polytope Studio	PT_Male_Knight_01/02, PT_Female_Knight_01/02 (w/ HumanMapAnims controller)
soldier types (8 names)	AnimalEffect	Polytope Studio	PT_Male_Soldier_01/02, PT_Female_Soldier_01/02 (w/ HumanMapAnims controller)
archer types (3 names)	AnimalEffect	Polytope Studio	PT_Male_Archer_01/02, PT_Female_Archer_01/02 (w/ HumanMapAnims controller)
militia types (8 names)	AnimalEffect	Polytope Studio	PT_Male_Militia_01/02, PT_Female_Militia_01/02 (w/ HumanMapAnims controller)
peasant types (9 names)	AnimalEffect	Polytope Studio	PT_Male_Peasant_01, PT_Female_Peasant_01_a (w/ HumanMapAnims controller)
clown	AnimalEffect	Clown Pack	Clown, Fat Clown (w/ per-prefab controller overrides)
giant	AnimalEffect	Polytope Studio	PT_Male/Female_Peasant at 3x scale (w/ HumanMapAnims controller)
ogre, troll	AnimalEffect	Orc-Ogre Pack	OrcOgre_Animated (w/ OgreMapAnims controller)
bear	AnimalEffect	Animal Pack Deluxe	Brown_bear
boar	AnimalEffect	Animal Pack Deluxe	Wild_boar
crocodile	AnimalEffect	Animal Pack Deluxe	Crocodile
snake	AnimalEffect	Animal Pack Deluxe	Viper
crab	AnimalEffect	Animal Pack Deluxe	Crab
frog	AnimalEffect	Animal Pack Deluxe	Common_frog, Common_frog_v2, Common_frog_v3
rabbit	AnimalEffect	Animal Pack Deluxe	Wild_rabbit, Wild_rabbit_v2
salamander	AnimalEffect	Animal Pack Deluxe	Fire_salamander
scorpion	AnimalEffect	Animal Pack Deluxe	Scorpion, Yellow_fattail_scorpion
stag	AnimalEffect	Animal Pack Deluxe	Deer, Deer_male
wild goat	AnimalEffect	Animal Pack Deluxe	Goat, Ibex
wild pig	AnimalEffect	Animal Pack Deluxe	Iron_age_pig, Iron_age_pig_v2
wolf, wolverine	AnimalEffect	Animal Pack Deluxe	Wolf
honey badger	AnimalEffect	HoneyBadger (Sketchfab)	HoneyBadger (w/ HoneyBadgerMapAnims controller)
raccoon	AnimalEffect	Raccoon (Sketchfab)	Raccoon (w/ RaccoonMapAnims controller)

Human-type beasts

34 human-type beast names use 3D Polytope Studio characters grouped into 5 archetypes. Each archetype uses a shared HumanMapAnims.controller that retargets Clown animation clips (idle, walk, attack, damage) via Unity's Humanoid system. One additional human type (psychopath) uses the 2D Butcher sprite from DungeonMonsters2D.

Archetype	Polytope Type	Beast Names (count)
Knight (heavy armor)	Knight M/F x2	cultist, heretic, cannibal, terrorist, cossack, desperado (6)
Soldier (medium armor)	Soldier M/F x2	bandit, brigand, robber, highwayman, marauder, dacoit, freebooter, mobster (8)
Archer (light armor, ranged)	Archer M/F x2	thief, pirate, buccaneer (3)
Militia (light armed)	Militia M/F x2	hooligan, street tough, ruffian, scalawag, ne'er-do-well, crook, miscreant, asshole (8)
Peasant (unarmed)	Peasant M/F	agitator, instigator, rabble-rouser, separatist, particularist, nihilist, proud boy, rebel, traitor (9)

Asset packs: Polytope Studio - Lowpoly Medieval Characters (Soldiers, Knights, Militia, Archers, Peasants)

| Butcher (armed loner) | DungeonMonsters2D Butcher | psychopath (1) |

No custom animation (falls back to generic vultures)

Ordered by spawn likelihood (most common first):

Beast	Likelihood	Notes
mammoth	0.10	Fantasy/prehistoric
tiger	0.10	Big cat
elephant	0.04	Large animal
hippogryph	0.04	Fantasy creature
hippopotamus	0.04	Large animal
lion	0.04	Big cat
chimpanzee	0.04	Primate
velociraptor	0.02	Dinosaur
unknown	0.00	Intentional fallback

Tips

• Keep effects lightweight; multiple provinces may have beasts simultaneously
• Use ParticleSystemScalingMode.Hierarchy so effects scale with the map zoom
• Set appropriate sortingOrder on renderers (existing effects use 102-104)
• For animated prefabs, set AnimatorCullingMode.AlwaysAnimate since UI elements may be considered offscreen by the culling system
• For 3D models (AnimalEffect), set renderQueue=4000 and ZTest=Always on materials to prevent clipping behind the map