t1k:unity:dots-core:progression
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | medium |
| Tools | — |
Keywords: dialogue, idle, level up, meta-currency, prestige, progression, quest, RealmEra, reward pipeline, xp curve
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:progressionDOTS Progression — Level, Quest, Dialogue, Idle, Meta
Section titled “DOTS Progression — Level, Quest, Dialogue, Idle, Meta”Package:
com.the1studio.dots-progression— namespaceDOTSProgression.*Related skills:t1k:unity:dots-core:ecs(API) ·t1k:unity:dots-combat:rpg(stats pipeline)
When This Skill Triggers
Section titled “When This Skill Triggers”- Implementing XP → Level-Up pipeline with formula-driven thresholds
- Building quest objectives (kill count, zone visit, collection) with progress tracking
- Adding dialogue trees with branching and speaker/text data
- Implementing idle generators: offline catch-up, multiplier stacking, prestige reset
- Meta-progression: permanent unlocks, meta-currency, encounter pool manipulation
- Granting XP, currency, or combined rewards in response to any game event (kill, quest, daily login, combo)
- Using
RewardApplier,RewardSpec,RewardRequestEvent, orEntityEventRewardSystem - Saving/loading run state (
runstate.bin,RunStateData,RunStateSerializer), bumping a save schema version, or debugging a rejected/corrupt save
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
reward-applier-guide.md (references/reward-applier-guide.md) | RewardApplier / RewardSpec / EntityEventRewardSystem — exact API signatures, 4 use-cases (RPG kill, puzzle combo, idle catch-up, battle-pass streak), pattern for domain reward systems, gotchas |
goal-ladder-guide.md (references/goal-ladder-guide.md) | DOTSProgression.Ladder reward-grant step — LadderRewardCursor / LadderRewardGrantSystem, the Unlocks-vs-Rewards split, the dots-economy storage deposit path, wiring checklist, gotchas |
feature-history.md (references/feature-history.md) | Dated additions kept as reference — BattlePass Analytics Hook, Realm Unlock Pipeline, H2 SystemBase→ISystem migrations |
run-state-persistence.md (references/run-state-persistence.md) | DOTSProgression.Persistence — the runstate.bin MemoryPack save (PersistenceConstants / RunStateData / RunStateSerializer), the schema-v6 migration ladder (v7 SimTick pending, unmerged), and why it is a different counter from dots-core’s SaveConstants.FormatVersion (now 4, breaking). Also the DOTSProgression.Checkpoint SSOT + dead-PhaseStatus notes |
Public Components
Section titled “Public Components”Regenerated against source 2026-08-23 — the previous table diverged on 3 fabricated system names, 1 misattributed group, and a Quest/Dialogue component shape that never matched source. Full audit:
plans/reports/audit-260822-dots-progression-skill-drift.md.
| Component | Type | Purpose |
|---|---|---|
Experience | IComponentData (DOTSCore.Stats) | float Current, ToNextLevel (recomputed on level-up, clamped ≥ 1), BaseXP, Exponent (power-curve, default); XpCurveKind CurveKind selects power vs. LinearBase/LinearCoefficient/GeometricBase (linear-geometric) |
Level | IComponentData, IEnableableComponent (DOTSCore.Stats) | int CurrentLevel, MaxLevel — LevelUpSystem stops incrementing once CurrentLevel == MaxLevel |
DirtyTag | IComponentData (tag), IEnableableComponent (DOTSCore) | Enabled by LevelUpSystem on any level gained; consumed by DerivedStatsSystem. Not the same type as StatsDirtyTag (also real, but not what LevelUpSystem touches) |
LeveledUpEvent | IComponentData (tag), IEnableableComponent (DOTSCore.Stats) | Enabled alongside DirtyTag by LevelUpSystem; UI/analytics consumers poll it for a level-up signal |
QuestDefinition | IBufferElementData | int QuestId, RequiredCount, QuestObjectiveType ObjectiveType, TargetId, RewardXP, RewardCurrencyType, RewardCurrencyAmount, PrerequisiteQuestId (-1 = none), DownstreamXpOverride |
QuestProgress | IBufferElementData | int QuestId, CurrentCount, QuestState State, InitialState |
QuestCompletedEvent | IBufferElementData (one-tick, optional buffer) | int QuestId, RewardXP, RewardCurrencyType, RewardCurrencyAmount, DownstreamXpOverride — emitted by QuestProgressSystem (auto-collect path) or QuestRewardSystem (standard path) |
DialogueNode | IBufferElementData | int NodeId, NextNodeId (-1 = end), SpeakerId, TextId — integer lookups resolved by managed-side localization/character DB, no inline text |
IdleGenerator | IBufferElementData | float BaseRate (unmodified), CurrentRate (resolved after multipliers — what IdleProductionSystem/OfflineCalculationSystem actually tick), int ResourceType, float Accumulated |
OfflineProgress | IComponentData (singleton) | long LastLoginTicks, float MaxOfflineHours (the real offline cap field), bool CalculationPending |
PrestigeConfig | IComponentData (singleton) | int PrestigeLevel, float BonusPerPrestige, TotalBonus (resolved, clamped), bool PrestigeRequested |
MetaCurrency | IComponentData (singleton) | int Value |
MetaUnlock | IBufferElementData | FixedString64Bytes UnlockId, bool Unlocked, int Cost |
public enum QuestObjectiveType : byte{ Kill, Collect, Deliver, Talk, Explore, Craft, ReachLevel, // player-action (0-6) EncounterCleared = 10, BossCleared, LoreFragmentCollected, RunCompleted, // system-driven, auto-collect Custom = 255,}public enum QuestState : byte { Available, Active, Completed, Failed, TurnedIn }Checkpoint Bridge Types (v4.0.1 — Phase 3)
Section titled “Checkpoint Bridge Types (v4.0.1 — Phase 3)”Namespace:
DOTSProgression.Bridge·DOTSProgression.Checkpoint
These types complete the checkpoint restore path. Bridge buffers decouple DOTSProgression from DOTSEconomy / DOTSInventory by using plain int keys instead of hard references.
Bridge buffers (CurrencyBridgeData, InventoryBridgeBuffer), the ownership contract, CheckpointRestoreRequest / CheckpointRestoreSystem, the restore flow and usage code: references/checkpoint-bridge.md.
Public Systems
Section titled “Public Systems”Full detail: references/public-systems.md. Read it before acting on this topic.
Common Patterns
Section titled “Common Patterns”XP → Level-Up
Section titled “XP → Level-Up”// LevelUpSystem (dots-core.Stats, StatsSystemGroup) — IJobEntity, cascading level-up:while (exp.Current >= exp.ToNextLevel && level.CurrentLevel < level.MaxLevel){ exp.Current -= exp.ToNextLevel; level.CurrentLevel++; exp.ToNextLevel = /* CurveKind-selected formula (Power or LinearGeometric), clamped >= 1 */;}// On any level gained this tick — NOT a "LevelUpTag" (that type never existed):if (StatsDirtyLookup.HasComponent(entity)) StatsDirtyLookup.SetComponentEnabled(entity, true); // DirtyTagif (LeveledUpLookup.HasComponent(entity)) LeveledUpLookup.SetComponentEnabled(entity, true); // LeveledUpEventQuest objective progress
Section titled “Quest objective progress”// QuestProgressSystem (QuestSystemGroup) — reads EntityEvent buffers per entity, matches// QuestDefinition.TargetId (0 = wildcard). Standard objectives increment QuestProgress.CurrentCount// and set QuestState.Completed at threshold. The 4 system-driven objectives (EncounterCleared/// BossCleared/LoreFragmentCollected/RunCompleted) skip Completed and jump straight to TurnedIn,// emitting QuestCompletedEvent inline.// QuestRewardSystem (UpdateAfter) then grants XP for everything still at Completed via// RewardApplier.ApplyXP, and transitions it to TurnedIn.Idle catch-up
Section titled “Idle catch-up”// OfflineCalculationSystem.OnUpdate — one-shot, gated by CalculationPending:if (!offline.ValueRO.CalculationPending) continue;offline.ValueRW.CalculationPending = false;
long nowTicks = System.DateTimeOffset.UtcNow.Ticks; // WALL clock, not sim timelong elapsedTicks = nowTicks - offline.ValueRO.LastLoginTicks;if (elapsedTicks <= 0) continue;
double elapsedHours = elapsedTicks / (double)System.TimeSpan.TicksPerHour;if (elapsedHours > offline.ValueRO.MaxOfflineHours) elapsedHours = offline.ValueRO.MaxOfflineHours;
// Stay in double through the accumulation — casting to float first loses ~1 s/day// at 30-day durations. Cast only the per-generator result.double elapsedSeconds = elapsedHours * 3600.0;foreach (var generator in SystemAPI.Query<RefRW<IdleGenerator>>()) generator.ValueRW.Accumulated += (float)(generator.ValueRO.CurrentRate * elapsedSeconds);
offline.ValueRW.LastLoginTicks = nowTicks; // re-arm the anchorPrestige reset
Section titled “Prestige reset”// PrestigeSystem — a SOFT reset. It does NOT destroy entities, and does not touch// RunScopeSingleton / RunScopeBuffer:prestige.ValueRW.PrestigeLevel++;float rawBonus = 1f + prestige.ValueRO.PrestigeLevel * prestige.ValueRO.BonusPerPrestige;prestige.ValueRW.TotalBonus = math.clamp(rawBonus, 1f, PrestigeConstants.MAX_BONUS_MULTIPLIER);
// Reset every IdleGenerator's fractional accumulator, then re-stamp any MultiplierStack entry// sourced from "prestige" to the new TotalBonus. A consumer wanting a run-scoped entity wipe// on prestige (e.g. via RunScopeSingleton/RunScopeBuffer) must do that itself — PrestigeSystem// only ever touches PrestigeConfig, IdleGenerator, and MultiplierStack.foreach (var generator in SystemAPI.Query<RefRW<IdleGenerator>>()) generator.ValueRW.Accumulated = 0f;Cross-Package Interactions
Section titled “Cross-Package Interactions”| Direction | Package | Detail |
|---|---|---|
| Depends on | DOTSCore base | SystemAPI, ECB, FixedString |
| Depends on | DOTSCore.Stats | DirtyTag (enableable) signal enabled by LevelUpSystem on level-up, consumed by DerivedStatsSystem — not StatsDirtyTag (a real but different type LevelUpSystem never touches) |
| Depends on | DOTSCore.Pickup | XPCollectionSystem writes the DOTSCore.Stats-owned Experience component when a pickup is collected |
| Used by | DOTSCombat | Kill events feed QuestProgressSystem |
Demo Precedents
Section titled “Demo Precedents”- BackpackCrawler — XP/Level pipeline + quest board with item-collect objectives
- IdleRPGDemo — IdleGenerator × 6 resources + offline catch-up + prestige loop
- RogueliteDemo — MetaUnlock tree, MetaCurrency from runs, encounter pool scaling
Run-State Persistence
Section titled “Run-State Persistence”Package:
DOTSProgression.Persistence· Full detail:references/run-state-persistence.md
There are two save-version counters in this library and they are not the same number.
DOTSCore.SaveConstants.FormatVersion (4) governs the library-wide ECS snapshot under
<persistentDataPath>/saves/; PersistenceConstants.SCHEMA_VERSION (6) governs this
package’s MemoryPack runstate.bin blob (RunStateData / RunStateSerializer). They are
independent — bumping one does not bump the other, and a note about “the save version” that
doesn’t name its package is ambiguous.
⚠️ v7 (SimTick, order 19) is proposed in unmerged upstream PR #141 — do not treat it as shipped.
Also unmerged: PR #140, fixing a live v6 bug where a migrated save’s RunSeed = 0 (the pre-v6
hardcoded sentinel) unconditionally clobbers the host’s freshly-generated seed on load. Full detail
in references/run-state-persistence.md.
Always construct with RunStateData.CreateNew() — the parameterless constructor leaves
SchemaVersion = 0 (rejected as corrupt) and SelectedWagerId = 0 (collides with a valid wager
index). Every field’s [MemoryPackOrder(N)] is a permanent wire contract; orders 0–18 are taken,
new fields take 19+, and a bump ships with a SCHEMA_VERSION + MAX_KNOWN_SCHEMA_VERSION change
together. UnlockedSkillNodeIds loads as null, not empty, on pre-v4 saves.
Full schema ladder, the SaveConstants 3→4 breaking-bump post-mortem, and the
DOTSProgression.Checkpoint SSOT (CurrentPhase/CurrentStep, dead PhaseStatus, the
three-bucket PhaseClearHistory): references/run-state-persistence.md.
Goal Ladder — reward-grant step
Section titled “Goal Ladder — reward-grant step”Package:
DOTSProgression.Ladder· Full detail:references/goal-ladder-guide.md
A ladder is a linear list of GoalSteps baked into a blob; GoalLadderState.ActiveStepIndex is the cursor. The two halves of a step payout are applied by DIFFERENT systems — GoalAdvanceSystem applies GoalStep.Unlocks inline, and LadderRewardGrantSystem ([UpdateAfter(typeof(GoalAdvanceSystem))], shipped in B4) applies GoalStep.Rewards into the world’s PrimaryStorageTag hopper via DOTSEconomy.Storage.StorageUtility.Reserve. Rewards were previously documented as “consumer-applied” and applied by nobody; they are now applied in-library, so a consumer-side ladder reward applier will double-grant.
Pay-out requires all three of GoalLadderReference, LadderRewardCursor (int GrantedUpTo, a monotonic watermark — advance with math.max, and persist it alongside GoalLadderState), and a DynamicBuffer<GoalStepCompletedEvent>. Miss the cursor component and the ladder advances while paying nothing, with no error.
TryGetSingletonEntity<PrimaryStorageTag> proves only the TAG exists — the follow-on GetBuffer<StoredItem> / GetComponent<StorageCapacity> need their own HasBuffer / HasComponent guards or a split bootstrap throws. And a thrown ISystem exception is not a clean failure: ComponentSystemGroup logs it without disabling the system, so it becomes per-frame console spam.
Dated feature history — BattlePass Analytics Hook, Realm Unlock Pipeline, SystemBase→ISystem migrations
Section titled “Dated feature history — BattlePass Analytics Hook, Realm Unlock Pipeline, SystemBase→ISystem migrations”Three dated additions (the BattlePass analytics hook, the Realm unlock pipeline, and the H2 SystemBase→ISystem migrations) are kept in full in references/feature-history.md. Read it only when working in those subsystems.
Hard rules
Section titled “Hard rules”Full detail: references/hard-rules.md. Read it before acting on this topic.