prosperon/docs/entities.md

title, type

title	type
Entities	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:

// 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:

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

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:

[
  {"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:

// 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 provides several ways to find and iterate entities:

var world = use('world')

// Iterate all entities
world.each(function(entity) {
  log.console(entity)
})

// Filter entities by predicate — returns array
var enemies = world.query(function(e) { return e.team == 'enemy' })

// Find first matching entity
var player = world.find(function(e) { return e.is_player })

// Get entity count
var n = world.count()

Updating Entities

Call world.update(dt) each frame to tick all entities that have an update(dt) method:

// In your core.start() update callback:
core.start({
  update: function(dt) {
    world.update(dt)
  }
})

Loading Levels

Load a level from a JSON array of entity definitions:

world.load_level([
  {"script": "entities/goblin", "pos": {"x": 100, "y": 200}},
  {"script": "entities/tree", "pos": {"x": 300, "y": 100}}
])

Each entry's script field is loaded via use() as the prototype. All other fields are applied as overrides.

Clearing the World

Remove and destroy all entities:

world.clear()

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.