Shadows Configuration

Files

File	Purpose
`config.yml`	Extraction, summon, AI, regions, ModelEngine
`shadow-archetypes.yml`	Per-archetype stats, abilities, `model-engine-id`
`leash-preferences.yml`	Per-player leash distance (generated)

Debug (`debug`)

All debug flags default to false (production-safe). Enable selectively when troubleshooting.

Key	Description
`enabled`	Master verbose logging
`model-engine` / `summon` / `ai` / `animations` / `mounts` / `resource-pack`	Per-subsystem logs

ModelEngine (`modelengine`)

Key	Description
`install-blueprints`	Copy bundled `.bbmodel` to ModelEngine on enable
`overwrite-blueprints`	Replace existing blueprint files
`reload-after-install`	Run `/meg reload` after install (default off)
`debug`	Verbose ModelEngine logging
`reapply-after-pack-load`	Re-apply models when resource pack loads
`pack-load.warning-delay-ticks`	Wait after `DOWNLOADED` before stall warning (default 1800 = 90s)
`pack-load.extended-poll-max-ticks`	Poll `SUCCESSFULLY_LOADED` for at least this long (default 1800; code also covers the warning window)
`pack-load.auto-resend-on-stall`	Leave false — mid-apply resend restarts the client load loop

Required: ModelEngine plugin + merged resource pack (Core resource-pack.merge-modelengine-pack).

V2 blueprint layout

Path	Purpose
`modelengine/blueprints/v1/`	Archived legacy models
`modelengine/blueprints/v2/custom/`	Ascension-built models
`modelengine/blueprints/v2/downloaded/`	Imported pack models
`modelengine/blueprints/v2/manifest.json`	Active install list

Per archetype: model-engine-id = shadow palette, wild-model-engine-id = *_wild palette (gate dungeons).

Archetype abilities (`abilities`)

Key	Description
`rideable`	Allow player mount (WASD to ride, right-click to dismount)
`mount-flight`	Flying mount: walks on the ground, `F`/`Space` to take off, `Space` up, look down to dive, `F` to land
`fire-breath`	Mounted left-click breath (fires even at empty air) + AI breath at range in combat
`mount-seat-y-offset` / `mount-seat-z-offset`	Rider seat offset
`owner-heal-hearts-per-second` / `heal-radius`	Passive aura heal

Dragon Monarch ships with mount-flight and fire-breath enabled.

Global mount tuning lives under abilities in config.yml:

Key	Default	Effect
`mount-fly-speed` / `mount-ground-speed`	`0.45` / `0.22`	Blocks per tick while riding

The rider is re-seated onto the model's back each tick (mount-seat-y-offset / mount-seat-z-offset per archetype). The seat re-position keeps your camera rotation untouched, so mouse-look stays smooth.

Notable archetypes

ID	Role	Notes
`kamish`	MONARCH rideable flying dragon	Solo-Leveling western dragon. Shadow = black scales / glowing purple horns + underbelly; wild = red scales. Has an apex "Inextinguishable Flame" breath — wider, longer, with Dragon's Fear (blindness + slow) and a blinding flame burst. Extracted from `ENDER_DRAGON`.
`granite_sentinel`	EPIC tank golem	Slow, high-HP melee bruiser. Shadow = obsidian stone with glowing purple runes; wild = granite grey with molten cracks. Extracted from `IRON_GOLEM`.

Both ship as wild + shadow blueprint pairs (ascension_kamish(_wild), ascension_granite_sentinel(_wild)) with the full animation set (idle, walk, attack, summon, recall, death — dragon also fly/ride/breathfire).

Display showcase (`display`)

Key	Description
`interact-speech-format`	NPC speech wrapper for interact messages
`interact-presets`	Reusable click/proximity presets (`--interact <id>`)

Showcase patrol and animation state is stored on the entity (PDC), not in YAML.

Staff: /shadows admin display grid both 4 (ascension.shadow.display.grid). Repo: docs/MODELENGINE_SHADOWS.md, python tools/v2_shadow_counterparts.py.

Extraction (`extraction`)

Key	Description
`min-rank`	Minimum hunter rank (default `C`)
`base-success`	Base extraction chance
`rank-success-bonus-per-tier`	Bonus per rank tier
`boss-bonus` / `boss-power-multiplier`	Boss kill modifiers
`offer-timeout-seconds`	Pending offer duration
`wild-kill-enabled`	Extraction from gate/dungeon wild mobs
`rare-archetypes`	Special rolls (e.g. Void Wyvern / Kaisel)

Summon & army (`summon`)

Key	Description
`max-active-summons`	Max shadows out at once
`default-behavior-mode`	`SQUAD`, `FOLLOW`, `FREE_ROAM`, etc.
`max-leash-blocks`	Default roam distance
`leash-permissions`	Map blocks → permission node
`mana-cost-per-tier`	Mana per summon by rank tier
`nameplate`	Floating name format + height
`particles.enabled`	Master switch for summon/dismiss/hit VFX
`particles.ambient-aura`	Continuous aura while idle/following (default `false`)
`ai.*`	Pathing, combat, squad formation, LOD

Nameplate (`summon.nameplate`)

Floating label above summoned shadows. Uses a TextDisplay teleported above the mob each AI tick (not a passenger), so it stays with the shadow as it moves. ModelEngine hides the base entity nameplate, so this label is the visible tag.

Key	Default	Effect
`enabled`	`true`	Show floating labels
`format`	multi-line	Placeholders: `{name}` `{owner}` `{rank}` `{hp}` `{maxhp}` `{health_bar}` — use `\n` for a second line
`height-scale`	`1.0`	Multiplier applied to the computed model height
`height-offset`	`0.45`	Clear space (blocks) above the model top
`model-heights`	map	Exact model-top height per `model-engine-id` (overrides the auto value) — e.g. `ascension_void_dragon: 4.6`

Default format shows shadow name + owner on line 1, and rank + HP bar on line 2. Applies to both summoned shadows and showcase (display) mobs (showcase uses its own label path).

Tall ModelEngine customs can float their name too low (the offset is based on the vanilla hitbox, not the model). Tune height under the keys above.

Storage capacity comes from AscensionCore rank shadow-capacity.

Sounds (`sounds`)

Vanilla event SFX for summoned shadows and wild dungeon mobs, keyed by archetype particle-profile (orc, wolf, drake, void, crystal, …). Entities are silent; these replace attack / hurt / death / summon chatter via ShadowSoundService.

Key	Default	Effect
`enabled`	`true`	Master switch
`volume`	`0.7`	Base volume
`pitch-variance`	`0.15`	Random pitch jitter

Wild mobs (`wild-mobs`)

Dungeon/gate mobs with custom AI. Archetypes and models in shadow-archetypes.yml (wild-model-engine-id).

Key	Default	Notes
`cancel-player-knockback`	`true`	Cancels vanilla + damage knockback when wild mobs hit players (custom hit feedback also skips shove)
`entity-collidable`	`false`	Wild mobs do not shove players via collision boxes
`min-health`	`24`	HP floor for low-base entities

Regions (`regions`)

WorldGuard/Towny integration — where shadows can fight or extract.

To block summoning in a WorldGuard region, set the custom flag to deny:

/rg flag <region> ascension-shadows deny

With worldguard.unset-means: default and default-allow: true, a region with the flag unset allows shadows for everyone — the flag must be deny to block.

Shadow, wild and display mobs are spawned directly by the plugin and are governed only by the ascension-shadows flag — not by WorldGuard's generic mob-spawning/deny-spawn flags. A spawn-protected area (e.g. mob-spawning deny at server spawn) will no longer silently swallow shadow summons; use the ascension-shadows deny flag if you want shadows blocked there.

Bypass: operators, ascension.admin, and ascension.shadow.region.bypass skip region checks entirely. When such staff summon inside a region that would otherwise block shadows, they still summon but receive regions.messages.summon-bypass-notice so the bypass isn't mistaken for the region not working. Test the actual block with a non-op account (or /deop).

Messages (`regions.messages`)

Key	Shown when
`summon-denied`	Non-staff summons where shadows are denied
`summon-denied-worldguard`	Denied by a WorldGuard region
`summon-denied-towny`	Denied inside a Towny town
`enter-denied`	Walking into a denied region (army recalled)
`enter-allowed`	Leaving back into an allowed area
`summon-bypass-notice`	Staff summon inside a region that would block others

Chat (`chat`)

Key	Description
`clickable-army-list`	Clickable `/shadows list` in chat
`clickable-extract-offer`	Clickable extraction prompts

Naming (`naming`)

min-length, max-length, blocked-words, use-builtin-filter for shadow rename/bind.

Bond levels (`bond-levels`)

Every shadow carries its own bond level (1 → max-level). Levels are earned automatically while the shadow is summoned — there are no points to spend. See Bond levels for the player-facing explanation and the growth formula.

Key	Default	Meaning
`max-level`	`100`	Bond cap. A capped shadow earns no further XP.
`xp-base`	`50`	First term of the XP curve.
`xp-per-level`	`22`	XP to reach the next level is `xp-base + 22 × current level` (level 1→2 = 72 XP; 99→100 = 2,228 XP; 1→100 = 113,850 XP total).
`strength-per-level`	`0.008`	Growth budget per level. At the cap a shadow has unlocked `(max-level - 1) × 0.008` = 79.2%, which is then multiplied by the archetype's `growth` values.
`default-movement-speed`	`0.27`	Fallback base speed for archetypes whose `growth.base-movement-speed` is unset.
`xp-per-kill`	`25`	Bond XP per normal mob kill.
`xp-boss-kill`	`120`	Bond XP for a kill on any mob with more than 100 max health.
`share-xp-radius`	`24`	Blocks. Summoned shadows farther than this from the victim earn nothing; every shadow inside it earns the full amount (XP is not split).
`level-up-message`	`true`	Chat message + live stat/nameplate refresh on level-up.

Per-archetype scaling lives in shadow-archetypes.yml → growth (health-growth, damage-growth, base-movement-speed, movement-speed-per-level). Those multipliers decide how much a bond level is actually worth for that archetype.

VFX catalog (`vfx`)

Data-driven summon, combat, and ability particles for shadows, played through the shared VFX engine (gated by Core vfx.enabled / vfx.density and summon.particles.enabled). Element dust colors come from the suite palette by particleProfile (so a void shadow, a void weapon, and a void gate match). Effect ids: shadow.aura.<profile> / shadow.hit.<profile> (per-profile particle sets), shadow.aura.base / shadow.hit.base, shadow.rise, shadow.dissolve, shadow.exchange.* (Shadow Exchange swap), and shadow.fire_breath.cone / cone_apex / apex_burst (dragon breath). Layer format is the same as documented in the gates configuration VFX section.

On this page