@ratprez/entm

TypeScript ECS (Entity Component System) framework package for FiveM. This is the base package - it provides the core classes, component types, and math utilities used by entm-core and any module built on top of it.

This package is a companion to entm-core. It is not a standalone FiveM resource. Install it as a dev dependency in your module projects.

Installation

npm install @ratprez/entm

Testing

The package includes a comprehensive test suite built with Vitest:

npm test

Coverage: 138 tests across 8 test files covering all core ECS functionality including ComponentPool, World, View, System, Vec3 math, Profiler, and integration scenarios.

What's included

Core ECS

Export	Description
World	Manages entities, components, and systems
System	Base class to extend for your own systems
View	Iterates entities matching a set of component types
ComponentPool	Sparse set storage for a single component type
Component	Abstract base class for all components
Profiler	Frame-time measurement for systems

Components

Export	Description
EntityComponent	Abstract base for spawnable FiveM entities
CfxEntity	Holds a live FiveM entity handle
Ped	Client-side ped component
Vehicle	Client-side vehicle component
Transform	Position, rotation, scale

Math

Export	Description
vec3	Construct a Vec3 from values or a coords array
vec3Add vec3Sub vec3Scale vec3Len	Common vector operations

Decorators

Export	Description
@shared	Marks a component class as shared across modules

Usage

import { System, Component, vec3 } from "@ratprez/entm";
import type { World } from "@ratprez/entm";

class Health extends Component {
    current: number;
    max:     number;

    constructor(max: number) {
        super();
        this.current = max;
        this.max     = max;
    }
}

class HealthSystem extends System {
    override update(dt: number): void {
        for (const { health } of this.m_world.view(Health)) {
            // your logic here
        }
    }
}

declare function __registerModule(init: (world: World) => void): void;

__registerModule((world) => {
    world.addSystem(new HealthSystem(world));
});

License

ISC