Skip to content

t1k:unity:dots-core:progression

FieldValue
Moduledots-core
Version3.56.1
Effortmedium
Tools—

Keywords: dialogue, idle, level up, meta-currency, prestige, progression, quest, RealmEra, reward pipeline, xp curve

/t1k:unity:dots-core:progression

DOTS Progression — Level, Quest, Dialogue, Idle, Meta

Section titled “DOTS Progression — Level, Quest, Dialogue, Idle, Meta”

Package: com.the1studio.dots-progression — namespace DOTSProgression.* Related skills: t1k:unity:dots-core:ecs (API) · t1k:unity:dots-combat:rpg (stats pipeline)

  • 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, or EntityEventRewardSystem
  • Saving/loading run state (runstate.bin, RunStateData, RunStateSerializer), bumping a save schema version, or debugging a rejected/corrupt save
FileContents
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

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.

ComponentTypePurpose
ExperienceIComponentData (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)
LevelIComponentData, IEnableableComponent (DOTSCore.Stats)int CurrentLevel, MaxLevel — LevelUpSystem stops incrementing once CurrentLevel == MaxLevel
DirtyTagIComponentData (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)
LeveledUpEventIComponentData (tag), IEnableableComponent (DOTSCore.Stats)Enabled alongside DirtyTag by LevelUpSystem; UI/analytics consumers poll it for a level-up signal
QuestDefinitionIBufferElementDataint QuestId, RequiredCount, QuestObjectiveType ObjectiveType, TargetId, RewardXP, RewardCurrencyType, RewardCurrencyAmount, PrerequisiteQuestId (-1 = none), DownstreamXpOverride
QuestProgressIBufferElementDataint QuestId, CurrentCount, QuestState State, InitialState
QuestCompletedEventIBufferElementData (one-tick, optional buffer)int QuestId, RewardXP, RewardCurrencyType, RewardCurrencyAmount, DownstreamXpOverride — emitted by QuestProgressSystem (auto-collect path) or QuestRewardSystem (standard path)
DialogueNodeIBufferElementDataint NodeId, NextNodeId (-1 = end), SpeakerId, TextId — integer lookups resolved by managed-side localization/character DB, no inline text
IdleGeneratorIBufferElementDatafloat BaseRate (unmodified), CurrentRate (resolved after multipliers — what IdleProductionSystem/OfflineCalculationSystem actually tick), int ResourceType, float Accumulated
OfflineProgressIComponentData (singleton)long LastLoginTicks, float MaxOfflineHours (the real offline cap field), bool CalculationPending
PrestigeConfigIComponentData (singleton)int PrestigeLevel, float BonusPerPrestige, TotalBonus (resolved, clamped), bool PrestigeRequested
MetaCurrencyIComponentData (singleton)int Value
MetaUnlockIBufferElementDataFixedString64Bytes 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.

Full detail: references/public-systems.md. Read it before acting on this topic.

// 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); // DirtyTag
if (LeveledUpLookup.HasComponent(entity)) LeveledUpLookup.SetComponentEnabled(entity, true); // LeveledUpEvent
// 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.
// 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 time
long 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 anchor
// 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;
DirectionPackageDetail
Depends onDOTSCore baseSystemAPI, ECB, FixedString
Depends onDOTSCore.StatsDirtyTag (enableable) signal enabled by LevelUpSystem on level-up, consumed by DerivedStatsSystem — not StatsDirtyTag (a real but different type LevelUpSystem never touches)
Depends onDOTSCore.PickupXPCollectionSystem writes the DOTSCore.Stats-owned Experience component when a pickup is collected
Used byDOTSCombatKill events feed QuestProgressSystem
  • 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

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.

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.

Full detail: references/hard-rules.md. Read it before acting on this topic.