Sim objects¶

Overview¶

Objects on the map live in the sim layer (src/sim/core/objects/). They are pure logic – no PixiJS. The client uses ObjectFactory and TextureProvider to create and render them.

Folder structure¶

Hierarchy¶

AbstractObject (base/)
├── ColonistObject (colonist/)
├── LandscapeElementObject (base/)
│   ├── PineTreeObject (landscape/) – GatherableInterface
│   └── StoneChunkObject (landscape/) – GatherableInterface
└── ResourceObject (base/)
    ├── WoodLogObject (resources/)
    └── StoneBrickObject (resources/)

AbstractObject¶

Base for all map objects. Defines:

Interfaces¶

GatherableInterface¶

Objects that can be gathered (chop, mine):

• getDrop(): { type: string; quantity: number }[] – drops when gathered
• dispatchGatherAction(onComplete) – start gather work (rendering layer handles completion)

Implemented by: PineTreeObject, StoneChunkObject

StackableInterface¶

Objects with quantity:

• getQuantity(): number
• getMaxStack(): number

Implemented by: WoodLogObject, StoneBrickObject (via ResourceObject)

TextureProvider¶

Injected by the client. Used for getTexture():

• getTextureByPosition(row, col) – sprite sheet
• getTextureByAsset(path) – asset path
• getTextureFromSpriteSheet(path, frameCol, frameRow, cols, rows) – sprite sheet frames

ActionExecutor¶

Injected by the client. Used by jobs to run actions (chop, mine):

• executeAction(objectId, actionId, onProgress?, onComplete?, options?)
• canExecuteAction(objectId, actionId)

ColonistObject¶

• Skills – level and XP per skill (e.g. Woodworking, Mining)
• Needs – sleeping, drinking, eating, recreation (0–100, decay over time)
• Job – currentJobId, allowedJobTypes, canDoJob(), setJobAllowed()
• Haul – carriedObject, setCarriedObject()
• Needs logic – tickNeeds(), fulfillDrinking(), fulfillSleep(), getLowNeedMessages()
• Overlay – getOverlayDescriptor() (Zzz when sleeping, need messages with cooldown); setOverlayCooldownUntil(ts) called by view after bubble display time
• XP – addSkillXp(skillName, xp) – 1 XP per 0.1s of work

See Needs & movement for need decay and job creation.

Object types¶

ObjectManager¶

• Storage: Map<uuid, AbstractObject> and spatial index Map<tileKey, Set<uuid>>
• Add/remove: addObject(), removeObject(uuid), removeObjectAt(x, y)
• Move: moveObject(uuid, newX, newY) – updates spatial index
• Lookup: getObjectByUUID(), getObjectAt(x, y) (clickable), getObjectsAt(x, y) (spatial)
• Serialization: serialize(), deserialize(data, objectFactory)

ObjectFactory¶

Client (src/client/ui/utils/ObjectFactory.ts) creates objects from serialized data:

• Uses TextureProviderImpl for textures
• Maps type → constructor: pine_tree, stone_chunk, wood_log, stone_brick, colonist
• Passes colonist data (name, age, skills, needs, etc.) for ColonistObject

Adding a new object type¶

1. Create class in the appropriate subdir (objects/landscape/, objects/resources/, or objects/colonist/) extending AbstractObject, ResourceObject, or LandscapeElementObject from ../base/
2. Implement getType(), getName(), getTexture(), getDisplaySize(), getClickableSize(), getActions()
3. Export from the subdir index.ts and from objects/index.ts
4. Add case in ObjectFactory.createObject() (client) for the new type
5. If gatherable: implement GatherableInterface and register action (e.g. chop) in game data
6. If stackable: extend ResourceObject and implement getMaxStack()