Skip to content

t1k:unity:dots-combat:rpg

FieldValue
Moduledots-combat
Version3.33.3
Effortmedium
Tools—

Keywords: assembly_prefix, auto battler, auto-battler, battle strip, BDP, behavior tree, board placement, boss, bullet heaven, combat strip, cross-demo reuse, damage numbers, damage popup, doc_search, DOTS, draft shop, knowledge-retrieval, library api lookup, role-playing, round phase, RPG, spawn troops, survivor, thin demo wrapper, troop spawn, unity-dots-library, wave, which assembly, which package

/t1k:unity:dots-combat:rpg

The API surface of unity-dots-library is NOT indexed in this skill. It lives in the studio knowledge-retrieval corpus (mcp__knowledge-retrieval__*), regenerated from the library’s own docstrings on every push — The1Studio/unity-dots-library is fully enrolled (8,300 members across 102 assemblies when this was written; re-check with Step 0 below, never quote this number). A hand-kept type inventory drifts the moment the library moves: the previous version of this skill placed the Wave Manager in dots-core when it lives in DOTSCombat.Spawning, and listed 8 packages against 22 on disk. The corpus cannot drift that way, so the inventory moved there.

What this skill DOES carry — the three things a docstring cannot tell you:

  1. The package → namespace → corpus-assembly map (§ below) — the exact assembly_prefix values you may pass. The corpus indexes by asmdef name, and guessing a prefix silently truncates results (t1k:knowledge-retrieval § Scoping), so this table is the legal set.
  2. Conventions, gotchas and anti-patterns — cross-cutting rules, ordering constraints and incident-derived traps (§ Key Conventions, § Anti-Patterns, § Gotchas, references/module-incident-history.md).
  3. The reuse-first workflow — what to compose before writing anything (references/cross-demo-reuse-patterns.md).

Related skills: t1k-unity-dots-core-ecs, t1k-unity-dots-core-jobs-burst, t1k-unity-dots-combat-physics, t1k-unity-dots-rendering-graphics, t1k-unity-dots-nav-agents-navigation, t1k-unity-dots-core-architecture, t1k-unity-dots-inventory-grid, t1k-unity-dots-ai-behavior-designer-pro, t1k:knowledge-retrieval (query technique SSOT — this skill cites it, never restates it).


Looking up the library — corpus first, then confirm on disk

Section titled “Looking up the library — corpus first, then confirm on disk”

Query technique (phrase as an answer, mechanic noun + mechanism word, read rrf as an arm counter) is owned by t1k:knowledge-retrieval (its query-technique.md reference). This section is only the DOTS-library-specific shape of that workflow.

Two facts shape every step: references/cross-demo-reuse-patterns.md comes before Step 1 — its entry-point table already answers most “which library piece does X” questions, and a doc_search then only confirms the row is current — and the corpus is multi-repo (Cocos playables, GameFoundation.*, TheOne.*, UITemplate.* all share it), so an unscoped query is a studio-wide query, not a library query.

Step 0 — coverage + freshness. doc_list_indexed_repos({ query: "unity-dots-library" }). Expect matched: 1. Read last_commit and compare it with the submodule pointer (git -C Packages/unity-dots-library rev-parse HEAD). Equal → the corpus IS the library you compile against. Behind → a type added since that commit is invisible to doc_search; confirm absence on disk before calling anything greenfield. Ahead → the corpus may describe an API your pointer does not have yet (references/submodule-sync-guide.md). If only this call fails (permission-denied, or the agent’s tools: lacks doc_list_indexed_repos) while doc_search works, the sweep is downgraded, not invalidated: run Steps 1–3, report freshness as unknown, and let Step 3 carry the compile-pointer truth.

Step 1 — search by capability, scoped by assembly. doc_search({ query, assembly_prefix, limit: 10 }). Take assembly_prefix from the map below — never a package id (com.the1studio.dots-combat matches nothing useful) and never a family guess. A prefix is not a boundary: DOTSCombat.Spawning also matches DOTSCombat.Spawning.Authoring, which is usually what you want (runtime type + its baker in one page).

Two passes when the owning package is unknown: unscoped to find the assembly, then scoped to find the member. An unscoped query reliably lands the right assembly in its top hits, but it can bury the exact member (an unscoped wallet transaction source query surfaced CurrencyId/WalletUtility, never WalletTransactionSource; the same query scoped to DOTSEconomy ranked it first) and it can fill the page with confident hits from other repos (an unscoped behaviour-tree query returned 5/10 Cocos playable-ad members). The two failure shapes are mirror images — a wrong prefix hides the answer behind real members from the wrong assembly; no prefix hides it behind real members from the wrong repo — and the remedy is the opposite move each time. Never conclude absence from one pass.

Step 2 — deepen the winner. doc_get_member({ id }) with an id copied from the search result (never hand-built — t1k:knowledge-retrieval § Gotchas). You get the full <summary>, <remarks>, and cross_refs with resolved_id. Verify a cross-ref before following it; about half resolve by unscoped simple-name match.

Step 3 — confirm on disk at the pointer you compile against. The corpus proves the capability exists at last_commit; the file:line and current field set come from Packages/unity-dots-library/library-primitive-index.md (Pass 0 of docs/library-feature-discovery-protocol.md) or a grep of the source. Skipping this is how a correct corpus answer becomes a CS0117 at compile time.

Degrade, never fake. MCP tool absent or erroring → run Pass 0 + the three grep passes from docs/library-feature-discovery-protocol.md and mark the result unverified / corpus-unavailable, never greenfield. t1k:knowledge-retrieval § “When the MCP is absent”.

Seven capability queries (damage mitigation, waves, status-effect stacking, aggro/leash, stat derivation, a named constant, an exact type name) each returned the owning member first with summary_quality: high; a second, black-box run by an agent given only this skill answered five unseen questions (boss phase signal, weighted loot on death, Wallet v2 source enum, hit-stop request, BDP throttle flag) — four from docstrings alone, one needing Step 3 because the flag is vendor-declared. Both tables, with the library commit they were measured against, and every miss with its cause: references/corpus-lookup-probes.md.


  • Using DOTSCore., DOTSCombat., DOTSAI., DOTSBDP., DOTSInventory., DOTSProgression., DOTSEconomy., DOTSPuzzle.
  • Adding Health, Mana, DamageEvent, StatusEffect, StatModifier, WaveState, SummonConfig, TalentNode components
  • Implementing AI behaviors (aggro, patrol, flee, detection, party formation)
  • Setting up skill casting, projectiles, AoE, summon, talent tree effects
  • Working with inventory slots, equipment, loot drops, crafting, currency
  • Configuring spawners, respawn mechanics, wave rounds
  • Creating towers, barracks, walls, structure placement grid (Structures module)
  • Implementing boss phases, abilities, combos (Boss module)
  • Using CameraTarget, CameraTrauma, CameraImpulseRequest (DOTSCore), HitStopRequest (DOTSCore.Time)
  • Triggering save/load via SaveStateRequest, LoadStateRequest (DOTSCore)
  • Asking “which package / namespace / assembly owns X?” — answer with the map below + doc_search

Before writing ANY combat code in a demo, audit references/cross-demo-reuse-patterns.md. The library already covers ~80% of typical combat-demo needs (damage numbers, auto-battler round/phase flow, troop spawn, waves, boss encounters, behavior trees). The remaining ~20% is authoring + genre-specific glue. The full entry-point table (damage numbers, XP drops, auto-fire weapons, round/phase state machine, draft shop, spawn patterns, wave schedules, boss phase/ability/combo, navigation, canonical BDP trees) and decision flow live in that reference doc — do not re-derive it here.

Gold-standard “thin demo wrapper” template: Assets/Demos/RPG/BattleDemoSideView/ — 1 Runtime script (camera) + 4 Editor scripts; ALL gameplay is library composition.

Per docs/library-feature-discovery-protocol.md, if you need a feature that doc doesn’t mention, run § “Looking up the library” above (corpus sweep, then confirm on disk) BEFORE implementing new code. Update that doc with whatever you find.

→ Full reference: references/cross-demo-reuse-patterns.md


Package → namespace → corpus assembly map

Section titled “Package → namespace → corpus assembly map”

Full detail: references/package-namespace-corpus-assembly-map.md. Read it before acting on this topic.

  • Namespaces: DOTSCore, DOTSCombat, DOTSAI, DOTSBDP, DOTSInventory, DOTSProgression, DOTSPuzzle
  • Assembly refs: Add separate asmdef reference per package — no single monolithic ref
  • Constants: GameplayConstants (DOTSCore), CombatConstants, AIConstants, CameraConstants, SaveConstants — never hardcode. Which class owns which domain and the rules behind the values: references/module-incident-history.md § Constants; a field’s meaning: doc_search with kind_filter: ["F"]
  • Teams: TeamId.Value (byte); 255 = no team
  • Events (IBufferElementData): DamageEvent, HealEvent, KnockbackEvent, StatusEffect, AudioEvent, ScoreEvent are per-entity payloaded buffers; EntityEvent is singleton global queue
  • Events (IEnableableComponent): LeveledUpEvent, WaveEvent, PhaseTransitionEvent, BuildEvent, DemolishEvent, SummonEvent, TalentEvent, UpgradeEvent, SaveComplete, LoadComplete are stateless one-frame signals
  • Event cleanup: each system group has a *EventCleanupSystem (OrderFirst) clearing its events via IJobEntity — see references/event-conventions.md
  • Enableable tags: DeadTag, InvulnerableTag, CCState, KnockbackState — toggle via SetComponentEnabled
  • CC masks: CCMasks.AttackBlock, .CastBlock, .MoveBlock — never inline bitmask expressions
  • Combat formulas: CombatFormulas.ComputeAutoAttackDamage(), .EffectiveCooldown(), .FrameRngSeed() — never inline
  • Stat pipeline: BaseStats -> StatModifier buffer -> DerivedStats -> StatSyncSystem syncs Health.Max/Mana.Max
  • ⛔ Units doing 0 damage / not moving in a demo? A SubScene missing StatFormulaConfigAuthoring leaves every unit’s derived stats frozen at their baked zero (as of 2026-08-22, StatSyncSystem no longer stomps Health to 0/0 and kills them — it now idles them instead) — see gotcha #0 in t1k:unity:dots-combat:core.
  • Burst rule: All systems Burst-compiled EXCEPT SaveSystem/LoadSystem (file I/O)

Submodule Sync — Always Pull Before Diagnosing API Drift

Section titled “Submodule Sync — Always Pull Before Diagnosing API Drift”

If Packages/unity-dots-library/ is consumed as a git submodule and a consumer reports CS0103/ CS0246/CS0117 on a library symbol, the first hypothesis is submodule staleness, not library deletion — cd Packages/unity-dots-library && git fetch origin && git log --oneline HEAD..origin/main before treating the missing API as a real deletion/migration target. Full procedure + why refactor commits routinely land helper + consumer updates in the same commit (so staying stale hides the helper half): references/submodule-sync-guide.md.


Anti-PatternFix
Importing old com.the1studio.dots-rpgAdd specific package refs: dots-core, dots-combat, etc.
Using old DOTSRPG.* namespaceMap: Core->DOTSCore, Combat->DOTSCombat, AI->DOTSAI, BDP->DOTSBDP
Inline magic numbersUse domain constants class
Duplicate DamageEvent constructionUse DamageEvent.Create() factory
ISystem for TalentUnlockSystemUse SystemBase — Entities 1.4 BufferTypeHandle two-pass invalidation
SetComponentEnabled before buffer readsAll buffer reads MUST complete before any SetComponentEnabled
SaveSystem/LoadSystem with [BurstCompile]File I/O — Burst intentionally absent
WaypointSpeedZone mutating MoveSpeed.ValueUse WaypointFollower.SpeedMultiplier local field
Missing asmdef ref for cross-package typeEach package is separate — add explicit asmdef reference
Over-specific instance name for a library typeName the generic ROLE, not one concrete instance. ArrowRegistryTag/TeamArrowPrefab → Projectile*; MageAttack* → ProjectileAttack*/CasterAttack*. See Gotcha “Generic component naming” + library-quality-mandate-unity.md § “Naming charter” (SSOT)

General ECS anti-patterns: t1k-unity-dots-core-ecs. Dimension-agnostic design: t1k-unity-dots-core-architecture.

System Update Order: See references/system-ordering-guide.md for full ASCII diagram.


  • docs/library-feature-discovery-protocol.md — run the corpus-first reuse search before implementing new combat functionality; always update this skill regardless of outcome
  • rules/kit-wide-fix-discipline.md — if you find yourself injecting “use library X for Y” into a teammate brief, that knowledge belongs in this skill
  • references/cross-demo-reuse-patterns.md — canonical reuse-first reference (this skill’s combat-side companion to the discovery protocol)
  • t1k:knowledge-retrieval (core) — query technique, scoping, reading a result, reporting a miss. This skill’s § “Looking up the library” is the DOTS-specific shape of that workflow and cites it rather than restating it
  • Packages/unity-dots-library/library-primitive-index.md — the generated on-disk index (Pass 0 of the discovery protocol); the offline twin of the corpus, exact file:line at the pointer you compile against
FileWhat it holds
references/module-incident-history.mdPer-module gotchas, ordering constraints and call patterns salvaged from the retired API-inventory guides — what a docstring cannot tell you
references/cross-demo-reuse-patterns.mdReuse-first entry-point table and decision flow — read before writing any combat code
references/event-conventions.mdThe three event patterns (enableable signal, per-entity buffer, singleton buffer) and their cleanup contract
references/system-ordering-guide.mdSystem-group update order, the resolved-damage channel
references/combat-v5-migration.mdv5.0.0 shim removal, rename and struct-split tables, Wave-4 neutrality renames
references/submodule-sync-guide.mdPull before diagnosing API drift
references/corpus-lookup-probes.mdThe measured probe table behind § “Looking up the library” — re-run when the library or corpus moves

The API inventory that used to live beside these (core/combat/stats/skills/spawning/inventory/ai/navigation/new-modules/constants guides, the DOTSCombat namespace map) was retired in favour of the corpus — see the top of this skill.