John Alanbrook
83b798e365
New Hugo site in website/ with prosperon.dev theme (blue/gold/castle aesthetic), docs sidebar navigation, and content pages. Rewrote all doc files to align with the actual codebase: compositor+film2d rendering, use() modules (no global prosperon object), Pit language, script+JSON entity model. Added entities.md, front matter to all 70+ API docs, and updated API index for current module architecture. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
122 lines
3.2 KiB
Markdown
122 lines
3.2 KiB
Markdown
---
|
|
title: "Entities"
|
|
type: docs
|
|
---
|
|
|
|
# Entities and the World
|
|
|
|
Prosperon uses a **script + overrides** model for entities, similar to Source engine entities. An entity type is defined by a script (`.cm` module), and instances are records that override specific attributes.
|
|
|
|
## Entity Types
|
|
|
|
An entity type is a module that returns a prototype object:
|
|
|
|
```javascript
|
|
// entities/goblin.cm
|
|
var sprite = use('sprite')
|
|
|
|
return {
|
|
health: 100,
|
|
speed: 2,
|
|
image: "goblin.png",
|
|
|
|
init: function() {
|
|
this.sprite = sprite({
|
|
image: this.image,
|
|
pos: this.pos,
|
|
width: 32,
|
|
height: 32,
|
|
layer: 5
|
|
})
|
|
},
|
|
|
|
on_destroy: function() {
|
|
this.sprite.destroy()
|
|
}
|
|
}
|
|
```
|
|
|
|
The return value defines every valid field with a default. This prototype IS the schema — the editor and tooling can introspect it to know what fields exist and what their defaults are.
|
|
|
|
## Creating Entities
|
|
|
|
Use the `world` module to create entity instances:
|
|
|
|
```javascript
|
|
var world = use('world')
|
|
var goblin_proto = use('entities/goblin')
|
|
|
|
var goblin = world.add_entity(goblin_proto, {
|
|
pos: {x: 100, y: 200},
|
|
health: 50
|
|
})
|
|
```
|
|
|
|
The second argument overrides specific fields from the prototype. Unspecified fields keep their defaults.
|
|
|
|
## Entity Lifecycle
|
|
|
|
Entities have two lifecycle hooks:
|
|
|
|
- `init()` — called when the entity is created (after overrides are applied)
|
|
- `on_destroy()` — called when the entity is removed from the world
|
|
|
|
```javascript
|
|
world.destroy_entity(goblin)
|
|
```
|
|
|
|
## Levels as Data
|
|
|
|
A level is a collection of entity instances stored as JSON — each entry is a script path plus attribute overrides:
|
|
|
|
```json
|
|
[
|
|
{"script": "entities/goblin", "pos": {"x": 100, "y": 200}, "health": 50},
|
|
{"script": "entities/goblin", "pos": {"x": 300, "y": 200}},
|
|
{"script": "entities/tree", "pos": {"x": 200, "y": 150}},
|
|
{"script": "entities/player_spawn", "pos": {"x": 50, "y": 50}}
|
|
]
|
|
```
|
|
|
|
The world loads this file, creates each entity from its prototype with the overrides applied. Since levels are JSON, they're easy to diff in source control and simple to generate from an editor.
|
|
|
|
## Composition via Modules
|
|
|
|
Entity behavior comes from composition, not inheritance. A goblin that patrols and has health uses separate modules:
|
|
|
|
```javascript
|
|
// entities/patrol_goblin.cm
|
|
var health = use('systems/health')
|
|
var patrol = use('systems/patrol')
|
|
|
|
return {
|
|
health: 100,
|
|
patrol_speed: 1.5,
|
|
patrol_points: [],
|
|
|
|
init: function() {
|
|
health.attach(this)
|
|
patrol.attach(this, this.patrol_points)
|
|
}
|
|
}
|
|
```
|
|
|
|
Each system module provides behavior that operates on the entity's data. No class trees, no diamond inheritance — just modules that read and write fields.
|
|
|
|
## Querying Entities
|
|
|
|
The world module lets you find entities:
|
|
|
|
```javascript
|
|
var world = use('world')
|
|
|
|
// All entities are tracked internally
|
|
// Query patterns are still being developed
|
|
```
|
|
|
|
## Override Rules
|
|
|
|
Overrides replace fields at the top level. If the prototype has `pos: {x: 0, y: 0}` and the override has `pos: {x: 50, y: 100}`, the entire `pos` is replaced. This is predictable and avoids ambiguity about partial nested merges.
|
|
|
|
Overrides should be pure data — field values only. No expressions, no conditionals, no logic. The script defines behavior; the override only tweaks data.
|