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)
tiger	AnimalEffect	ithappy Animals FREE	Tiger_001 (w/ TigerMapAnims controller)
elephant	AnimalEffect	Animal Pack Deluxe v2	African_elephant, Indian_elephant (w/ ElephantMapAnims controller)
mammoth	AnimalEffect	Animal Pack Deluxe v2	African_elephant, Indian_elephant (w/ ElephantMapAnims controller)
hippopotamus	AnimalEffect	Africa Animals Pack Low Poly V2	Hippopotamus (w/ HippopotamusMapAnims controller)
lion	AnimalEffect	Africa Animals Pack Low Poly V1	Lion, Lioness (w/ LionMapAnims controller)
velociraptor	AnimalEffect	Dino Pack Low Poly V1	VelociraptorColor1, VelociraptorColor2 (w/ VelociraptorMapAnims controller)
black panther	AnimalEffect	Africa Animals Pack Low Poly V1	BlackPanther (w/ BlackPantherMapAnims controller)
rhinoceros	AnimalEffect	Africa Animals Pack Low Poly V1	Rhinoceros (w/ RhinocerosMapAnims controller)
gorilla	AnimalEffect	Africa Animals Pack Low Poly V2	Gorilla (w/ GorillaMapAnims controller)
hyena	AnimalEffect	Africa Animals Pack Low Poly V2	Hyena (w/ HyenaMapAnims controller)
leopard	AnimalEffect	Africa Animals Pack Low Poly V2	Leopard (w/ LeopardMapAnims controller)
warthog	AnimalEffect	Africa Animals Pack Low Poly V2	Phacochoerus (w/ WarthogMapAnims controller)
emu	AnimalEffect	Australia Animals Pack V1	Emu (w/ EmuMapAnims controller)
kangaroo	AnimalEffect	Australia Animals Pack V1	Kangaroo (w/ KangarooMapAnims controller)
tasmanian devil	AnimalEffect	Australia Animals Pack V1	TasmanianDevil (w/ TasmanianDevilMapAnims controller)
hippogryph	DragonEffect	Heroic Fantasy Creatures Full Pack Vol 2	Hippogriff_PBR (w/ HippogryphMapAnims 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
chimpanzee	0.04	Primate
unknown	0.00	Intentional fallback

Using low-poly animal packs (Africa Animals, Dino Pack)

Assets from these packs (by the same author) require extra setup because they ship with Legacy animation import and include physics components that conflict with AnimalEffect. The workflow below applies to all of them:

• Africa Animals Pack Low Poly V1 (Lion, Lioness, Black Panther, Crocodile, Elephant, Giraffe, Rhinoceros, Tiger, Zebra)
• Africa Animals Pack Low Poly V2 (Hippopotamus, Antelope, Gorilla, Hyena, Leopard, Phacochoerus/Warthog)
• Dino Pack Low Poly V1 (Velociraptor, Brontosaurus, Pteranodon, Stegosaurus, T-Rex, Triceratops)
• Australia Animals Pack V1 (Chlamydosaurus/Frilled Lizard, Echidna, Emu, Kangaroo, Koala, Platypus, Tasmanian Devil)

Per-animal setup steps

1. Switch FBX import to Generic animation type. In the .fbx.meta file (location varies by pack):

   • Change animationType: 1 to animationType: 2
   • Change avatarSetup: 0 to avatarSetup: 1 (newer format) — older metas without avatarSetup will auto-create an avatar at runtime
   • Set loopTime: 1 on looping clips (idle, walk, eat, run) but NOT one-shot clips (attack, death, hurt) Unity will re-import the FBX with Mecanim-compatible clips when it next opens.

2. Create an AnimatorController in Assets/Eagle/Effects/ named <Animal>MapAnims.controller. Use the same 4-state pattern (idle, walk, eat, attack) as ElephantMapAnims. Reference the animation clips by their fileIDs from the FBX meta's internalIDToNameTable (type 74 entries) or fileIDToRecycleName (older format, type 7400000+). These IDs are stable across import type changes. Note: if the FBX names its idle clip idle1, create the controller state as idle but reference the idle1 clip by fileID.

3. Create an AnimalEffect prefab in Assets/Eagle/Effects/ named <Animal>Effect.prefab. Reference the pack's prefab as the animal prefab, and wire up the new AnimatorController. Multiple color/sex variants from the same or similar FBX can share one controller (e.g., Lion and Lioness). AnimalEffect will automatically strip the pack's legacy Animation, Rigidbody, and Collider components at spawn time, and add an Animator if the prefab doesn't already have one.

4. Register in ProvinceBeastsController with a case in GetEffectPrefab() and a test ContextMenu method.

5. Mark the effect prefab as Addressable with the beast-effects label in the Unity editor (Window > Asset Management > Addressables > Groups).

Notes

• The packs include both SingleTexture and TextureAtlas variants; use SingleTexture for best visual quality.
• Hippos have water-specific animations (idlewater, deathwater) that could be used for future water-province effects.
• The packs' prefabs include Rigidbody/BoxCollider components intended for gameplay use. AnimalEffect strips these automatically since it controls position directly.

Available animals not yet set up as beasts

These animals exist in the imported packs and could be set up as in-game beasts using the workflow above:

Africa Animals Pack V1 (already imported):

Animal	Good fit for	Notes
Giraffe (x2 variants)	giraffe beast	Tall model, may need larger scale
Zebra	zebra beast	Herd animal; good with higher animalCount

(Black Panther, Rhinoceros, Crocodile, Elephant, and Tiger already have effects.)

Africa Animals Pack V2 (already imported):

Animal	Good fit for	Notes
Antelope	antelope/gazelle beast	Fast-moving; good with higher moveSpeed

(Gorilla, Hyena, Leopard, Warthog, and Hippopotamus already have effects.)

Dino Pack Low Poly V1 (already imported):

Animal	Good fit for	Notes
Brontosaurus	brontosaurus/sauropod beast	Very large; needs big scale, low count
Pteranodon	pteranodon/flying beast	Has fly animation; could use DragonEffect-style flight
Stegosaurus	stegosaurus beast	Large herbivore
T-Rex	tyrannosaurus beast	Iconic predator; good as a solo beast
Triceratops	triceratops beast	Large herbivore; good for tough beast

(Velociraptor already has an effect.)

Australia Animals Pack V1 (already imported):

Animal	Good fit for	Notes
Koala	koala beast	Peaceful; good for low-threat province events
Echidna	echidna beast	Small, spiny
Chlamydosaurus (Frilled Lizard)	lizard beast	Has threat display animation
Platypus (Ornitorinco)	platypus beast	Semi-aquatic; unique

(Emu, Kangaroo, and Tasmanian Devil already have effects.)

None of the remaining animals above are currently in beasts.tsv.

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