Core Concepts

Entity System

The hierarchical entity architecture for all game objects.

The entity system is a class hierarchy where each level adds more capabilities. Choose the appropriate base class for your entity.

GameObject
  └── Actor
        ├── Entity3D
        └── LivingActor

GameObject

The base class for everything in the world.

import { GameObject } from '@mavonengine/core'

class MyObject extends GameObject {
  update(delta: number): void {
    // Called every tick/frame
  }
}

Properties

Property	Type	Description
`position`	`Vector3`	World position
`rotation`	`Vector3`	Euler rotation
`scale`	`Vector3`	Scale
`colliderMesh`	`Mesh \| undefined`	Optional physics collider mesh
`garbageCollect`	`boolean`	Set to `true` to mark for deletion

Methods

Method	Description
`abstract update(delta)`	Called every tick. Must be implemented.
`serialize()`	Returns a plain object for network/state serialization
`destroy()`	Cleanup resources

Actor

Extends GameObject with a pushdown automaton state machine.

import { Actor } from '@mavonengine/core'

class MyActor extends Actor {
  // State machine is managed automatically
}

Properties

Property	Type	Description
`state`	`EntityState[]`	Stack of active states
`stateHash`	`string`	Hash of the serialized state stack

The update(delta) method on Actor automatically delegates to the top state on the stack.

See State Machine for full details.

Entity3D

Extends Actor with Three.js model support and animations.

import { Entity3D } from '@mavonengine/core'
import type { GLTF } from 'three/examples/jsm/loaders/GLTFLoader'

class MyCharacter extends Entity3D {
  constructor(gltf: GLTF) {
    super()
    this.initModel(gltf)
  }
}

Properties

Property	Type	Description
`instance`	`Group`	Three.js object group (the model)
`animationMixer`	`AnimationMixer \| undefined`	Three.js animation mixer
`animationsMap`	`Map<string, AnimationAction>`	Named animation actions
`activeAction`	`AnimationAction \| undefined`	Currently playing animation

Methods

Method	Description
`initModel(gltf)`	Initialize from a loaded GLTF asset
`fadeToAction(name, duration)`	Smoothly transition to a named animation
`destroy()`	Removes model from scene and disposes geometry

LivingActor

Abstract extension of Actor for entities that can take damage and have health.

import { LivingActor } from '@mavonengine/core'

class MyEnemy extends LivingActor {
  health = 100
  maxHealth = 100

  isDead(): void { /* ... */ }
  takeDamage(amount: number): void { /* ... */ }
  heal(amount: number): void { /* ... */ }
}

Abstract members

Member	Description
`health`	Current health value
`maxHealth`	Maximum health value
`isDead()`	Called when health reaches zero
`takeDamage(amount)`	Apply damage
`heal(amount)`	Restore health

Implements the Damageable interface.

Game Loop

How BaseGame and Game drive the engine's update and render loops.

State Machine

Pushdown automaton pattern for managing complex entity behaviors.