Mob combat and presentation
Server-owned monster actions, patrol tactics and synchronized GeckoLib sound and weapon trails.
IsekaiCombatMob hosts shared monster profiles and per-entity combat state. Goblins use this foundation for mixed patrols, committed attack phrases, defensive reactions and client presentation.
What it does
The server selects actions, applies damage and moves the collision body. GeckoLib presents that state and emits sound and trail cues. MobAnimationAPI, under api.client, is the renderer facade; the types under internal.mob and internal.client.mob are project implementation, not an external API.
Runtime model
Profiles share action definitions. Each entity owns its current action, group, tactics and defense state. The tracked action index, sequence, start time and committed rate let clients seek the current phrase instead of restarting it when tracking begins.
Attack rate is generic.attack_speed / 4, clamped to 0.5–2. It is sampled when an action starts. Animation, event crossings, recovery and leap flight use that committed rate; an attribute change affects the next phrase. Damage events run on the server exactly once when their authored tick is crossed.
Group discovery considers at most 16 loaded allies, with a 40–46-tick (2–2.3-second) deadline checked by staggered perception. Revenge can refresh it immediately, with a 12-tick (0.6-second) debounce. Goblin cohorts admit 2 attackers; surviving leases transfer when a leader is replaced. Roles choose approach positions, while isolated wounded goblins retreat. Shields use facing and guard capacity; dodges move the collision body without granting invulnerability. Leap landing and dodge routes require supported, unobstructed terrain and do not load chunks.
GoblinEntity implements Monster, registers in SpawnGroup.MONSTER, uses SoundCategory.HOSTILE and disallows Peaceful persistence. All equipment variants share the goblin social family. Unowned packmates share the existing team protection resolver, including attributed projectiles and area spells; the hexer’s fire and frost do not harm its allies. Player ownership takes precedence over wild-pack allegiance.
Confirmed cohort deaths also drive morale. When at least half the recorded patrol has died and no more than 2 members remain, healthy survivors rout for 400 ticks (20 seconds). Missing or unloaded members are not casualties. A committed attack finishes before fleeing, but cannot chain. A fresh hostile hit cancels flight and prevents low-health retreat for 100 ticks (5 seconds), allowing retaliation. Rout time and recent casualties survive saving; fleeing leaders are not regroup destinations.
Shield users react to recent damage, melee swings, aimed bow draws and approaching physical projectiles. Projectile checks consider at most 16 candidates within 24 blocks every 2–3 ticks (0.1–0.15 seconds), predict body intersection and reject friendly, piercing, receding or obstructed shots. Raising takes 4 ticks (0.2 seconds). Guard has 48 capacity and costs 4 + damage × 1.5 per interception. Successful blocks attempt a counter through normal action and cohort gates. An uncontested guard begins lowering after 38 ticks (1.9 seconds), releases over 8 ticks (0.4 seconds), then cools down for 22 ticks (1.1 seconds). Axes or exhaustion break guard for 140 ticks (7 seconds). Custom magic projectiles are not classified as blockable arrows.
Goblin melee baselines are 6–11 damage, with action rates of 1.15–1.2; the hexer uses 1.1. gaitRate scales both run navigation and playback by 1.15 and sprint by 1.2, leaving walking at 1. Hexer fire actions summon Fireball’s summon shape at 0.7 output. hex_frost summons Icicle Lance at 0.65, while hex_rime retains Ice Burst at 0.45. Released circles follow the existing spell charge/release lifecycle.
Goblin death removal resolves the same EntityDeathFxRegistry policy that starts particlize. goblin_death delays dissolution by 36 ticks (1.8 seconds), dissolves over 32 ticks (1.6 seconds), then holds the model hidden for 32 ticks (1.6 seconds). This covers every variant’s 76–88-tick (3.8–4.4-second) corpse lifetime without exposing the final pose again.
Contracts
Sound cues
GeckoLib sound_effects keys resolve their effect string through the entity’s MobSoundPalette. Unknown cues are ignored. The goblin clips use step, land, attack and swing; server statuses provide hurt, death, block, guard_break, alert and retreat.
Palettes hold immutable sample lists. Each sample declares its sound-event ID and duration in ticks. Each cue supplies a channel, priority, cooldown, volume, probability and audible range. The mixer keeps one voice, foot and equipment slot per emitter, avoids immediate sample repeats and bounds nearby concurrent sounds. Higher-priority cues can replace weaker sounds; death stops that emitter’s other channels. Footsteps require grounded locomotion. Ambient calls are staggered and suppressed during combat.
Weapon capture cues
Place this instruction in a GeckoLib custom timeline key at authored tick 11. Times are authored ticks, with 20 ticks per second before attack-rate scaling:
ise:slash weapon 0 3.5 0 -0.5 10 0 11 17
| Argument | Type | Requirement | Meaning |
|---|---|---|---|
bone | string | Required; letters, digits or underscore | Animated bone to capture; weapon in this example. |
rootX rootY rootZ | finite numbers | Required; absolute value at most 1200 | Inner endpoint in model pixels relative to the bone pivot. |
tipX tipY tipZ | finite numbers | Required; absolute value at most 1200 | Outer endpoint in the same coordinate space. |
startTick endTick | finite numbers | Required; 0 ≤ start < end ≤ 1200; span at most 80 ticks (4 seconds) | Collection interval on the committed action clock. |
The bridge converts pixels to blocks and mirrors model X. Malformed instructions and elapsed windows are ignored. ise:slash_stop ends collection. Death, removal and a changed action sequence also stop it; already collected samples fade through the shared renderer.
The bone path selects isekaiexpansion:default_hybrid directly. It respects mob FX enablement and the shared trail renderer’s limits. It does not require an item stack or Better Combat attack metadata, and does not fire ATTACK_ANIMATION_START.
Extending it
Define a shared MobProfile, give the entity its tactical profile and sound palette, and author cues alongside its clips. MobAction callbacks own server effects; timeline instructions own presentation. Keep damage out of client keyframe handlers.
The mod initializes MobAnimationAPI.initClient() once. A GeckoLib renderer queries MobAnimationAPI.tracksWeapon(mob, boneName) before extra capture work. When true, call MobAnimationAPI.captureWeapon(mob, boneName, bonePivotMatrix) with the current view-space matrix at the animated bone pivot, before translating away from that pivot. GoblinRenderer.renderRecursively is the project example.
Verifying
Compile and run the isolated server regressions from the repository root:
./gradlew.bat compileJava
./gradlew.bat -I tools/mobs/mob-test.gradle runMobTest
The suite checks action timing, cancellation, group admission, shield facing, physical dodges and target-directed leaps at slow and fast rates. For presentation, launch the isolated review client with -I tools/mobs/client-review.gradle runGoblinReview, create a test world with commands enabled, then use /goblinreview setup, /goblinreview showcase and /goblinreview duel club. /goblinreview report records actions, sound dispatch and active capture windows. Inspect the actual rendered trails and poses as well as the report.
Related
Weapon slash FX covers trail profiles, materials and rendering limits.