t1k:unity:dots-core:pickup
| Field | Value |
|---|---|
| Module | dots-core |
| Version | 3.56.1 |
| Effort | low |
| Tools | — |
How to invoke
Section titled “How to invoke”/t1k:unity:dots-core:pickupDOTS Pickup — XP Gems & Magnet Mechanics
Section titled “DOTS Pickup — XP Gems & Magnet Mechanics”Package:
com.the1studio.dots-core— namespaceDOTSCore.PickupRelated skills:t1k-unity-dots-core-ecs(API) ·t1k-unity-dots-combat-rpg(stats/XP pipeline)
When This Skill Triggers
Section titled “When This Skill Triggers”- Implementing XP gem pickups, collectibles, magnet attraction
- Writing systems that pull entities toward a target within a radius
- Optimizing pickup/collection loops with distance-squared checks
- Spawning pickup entities on enemy death
Public Components
Section titled “Public Components”| Component | Type | Purpose |
|---|---|---|
XPPickup | IComponentData | Marks entity as collectible gem; float Value |
MagnetRadius | IComponentData | Player magnet: float Radius, float PullSpeed |
PickupConstants | static class | DefaultXPCollectionRadius (0.5f), DefaultXPCollectionRadiusSq (precomputed) |
Public Systems
Section titled “Public Systems”| System | Group | Role |
|---|---|---|
XPMagnetSystem | CoreSystemGroup | Pulls XPPickup entities toward MagnetRadius entities each frame |
XPCollectionSystem | CoreSystemGroup | Collects pickup within DefaultXPCollectionRadiusSq; adds XP; destroys entity via ECB |
Both carry [BurstCompile] + [RequireMatchingQueriesForUpdate] + [UpdateInGroup(typeof(CoreSystemGroup))].
Neither declares [UpdateAfter] — see Gotchas; the magnet→collect order is not pinned.
Entry Point
Section titled “Entry Point”// Player entity needs MagnetRadius; enemies drop XPPickup entities// Systems auto-run — no manual wiring required
// Spawn pickup on death:var gem = ecb.CreateEntity();ecb.AddComponent(gem, new XPPickup { Value = xpAmount });ecb.AddComponent(gem, new LocalTransform { Position = deathPos, ... });Common Patterns
Section titled “Common Patterns”Magnet flow (outer-inner loop with distance-squared)
Section titled “Magnet flow (outer-inner loop with distance-squared)”// XPMagnetSystem inner loop — avoids sqrt for Burstfloat distSq = math.distancesq(magnetPos, pickupPos);if (distSq < magnet.Radius * magnet.Radius){ // Vector FROM pickup TOWARD magnet — magnetPos - pickupPos, not the reverse. // normalizesafe (not normalize): this loop converges pickups onto the magnet, // so distSq == 0 is genuinely reachable and would NaN with a plain normalize. var dir = math.normalizesafe(magnetPos - pickupPos); pickupTransform.Position += dir * magnet.PullSpeed * deltaTime; // pull pickup toward magnet per frame}Collection pattern
Section titled “Collection pattern”// XPCollectionSystem — complete Experience writes before RW accessstate.Dependency.Complete();// then iterate, check DefaultXPCollectionRadiusSq, collectecb.DestroyEntity(pickupEntity); // EndSimulationECBSpawning pickups via ECB from IJobEntity
Section titled “Spawning pickups via ECB from IJobEntity”var gem = ecb.CreateEntity(chunkIndex);ecb.AddComponent(chunkIndex, gem, new XPPickup { Value = 10f });ecb.SetComponent(chunkIndex, gem, LocalTransform.FromPosition(pos));Cross-Package Interactions
Section titled “Cross-Package Interactions”| Direction | Package | Detail |
|---|---|---|
| Depends on | DOTSCore base | LocalTransform, ECB, SystemAPI |
| Depends on | DOTSCore.Stats | Experience component that XPCollectionSystem writes to |
| Used by | RPG demos | BattleDemo, ChaosForge, InventoryDemo all use pickup spawning |
Demo Precedents
Section titled “Demo Precedents”- BattleDemo2D — enemies drop XP gems on death; player magnetizes gems
- ChaosForgeDemo — MagnetRadius applies to player AND summons
- InventoryDemo — XP feeds LevelUp progression pipeline
Hard rules
Section titled “Hard rules”- Magnet→collect ordering is NOT declared. Both systems sit in
CoreSystemGroupwith no[UpdateAfter]between them, so the order comes from Unity’s system sort, not from intent. In practice a pickup collected before that frame’s magnet pull just lands one frame later, so it is latent rather than broken — but do not rely on the documented “magnet then collect” reading, and add an explicit[UpdateAfter(typeof(XPMagnetSystem))]if you ever need the guarantee. XPCollectionSystemmust complete pendingExperiencewrites before its own RW access. LevelUpJob from the previous frame may still be running. Callstate.Dependency.Complete()at the top ofXPCollectionSystem.OnUpdatebefore any Experience lookup.- PickupConstants squared form —
DefaultXPCollectionRadiusSqis the safe Burst form. Don’t callmath.sqrtin the hot loop — use the precomputed constant. - ECB sort key required when destroying pickups in parallel jobs: use
[ChunkIndexInQuery]as sort key forEndSimulationEntityCommandBufferSystem.ParallelWriter. - MagnetRadius is not IEnableableComponent — attach/detach by add/remove from authoring. If magnet needs toggling at runtime frequently, consider wrapping in IEnableableComponent variant.