t1k:unity:dots-combat:rpg
| Field | Value |
|---|---|
| Module | dots-combat |
| Version | 3.33.3 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:dots-combat:rpgDOTS Multi-Package Library Reference
Section titled “DOTS Multi-Package Library Reference”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:
- The package → namespace → corpus-assembly map (§ below) — the exact
assembly_prefixvalues 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. - Conventions, gotchas and anti-patterns — cross-cutting rules, ordering constraints and
incident-derived traps (§ Key Conventions, § Anti-Patterns, § Gotchas,
references/module-incident-history.md). - 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”.
Probes that prove the workflow
Section titled “Probes that prove the workflow”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.
When This Skill Triggers
Section titled “When This Skill Triggers”- 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
Cross-Demo Reuse — READ FIRST
Section titled “Cross-Demo Reuse — READ FIRST”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.
Key Conventions
Section titled “Key Conventions”- 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_searchwithkind_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 — seereferences/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
StatFormulaConfigAuthoringleaves every unit’s derived stats frozen at their baked zero (as of 2026-08-22,StatSyncSystemno longer stompsHealthto0/0and kills them — it now idles them instead) — see gotcha #0 int1k: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.
RPG-Specific Anti-Patterns
Section titled “RPG-Specific Anti-Patterns”| Anti-Pattern | Fix |
|---|---|
| Importing old com.the1studio.dots-rpg | Add specific package refs: dots-core, dots-combat, etc. |
| Using old DOTSRPG.* namespace | Map: Core->DOTSCore, Combat->DOTSCombat, AI->DOTSAI, BDP->DOTSBDP |
| Inline magic numbers | Use domain constants class |
| Duplicate DamageEvent construction | Use DamageEvent.Create() factory |
| ISystem for TalentUnlockSystem | Use SystemBase — Entities 1.4 BufferTypeHandle two-pass invalidation |
| SetComponentEnabled before buffer reads | All buffer reads MUST complete before any SetComponentEnabled |
| SaveSystem/LoadSystem with [BurstCompile] | File I/O — Burst intentionally absent |
| WaypointSpeedZone mutating MoveSpeed.Value | Use WaypointFollower.SpeedMultiplier local field |
| Missing asmdef ref for cross-package type | Each package is separate — add explicit asmdef reference |
| Over-specific instance name for a library type | Name 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.
Related rules and references
Section titled “Related rules and references”docs/library-feature-discovery-protocol.md— run the corpus-first reuse search before implementing new combat functionality; always update this skill regardless of outcomerules/kit-wide-fix-discipline.md— if you find yourself injecting “use library X for Y” into a teammate brief, that knowledge belongs in this skillreferences/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 itPackages/unity-dots-library/library-primitive-index.md— the generated on-disk index (Pass 0 of the discovery protocol); the offline twin of the corpus, exactfile:lineat the pointer you compile against
References in this skill
Section titled “References in this skill”| File | What it holds |
|---|---|
references/module-incident-history.md | Per-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.md | Reuse-first entry-point table and decision flow — read before writing any combat code |
references/event-conventions.md | The three event patterns (enableable signal, per-entity buffer, singleton buffer) and their cleanup contract |
references/system-ordering-guide.md | System-group update order, the resolved-damage channel |
references/combat-v5-migration.md | v5.0.0 shim removal, rename and struct-split tables, Wave-4 neutrality renames |
references/submodule-sync-guide.md | Pull before diagnosing API drift |
references/corpus-lookup-probes.md | The 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.