or run

tessl search

Version

Workspace: tessl
Visibility: Public
Created: 2 days ago
Last updated: 2 days ago
Describes: pkg:npm/ecos@0.2.x

docs

advanced

api-reference

guides

creating-entities.md custom-constructors.md using-methods.md using-presets.md working-with-extenders.md

index.md

tile.json

tessl/npm-ecos

tessl install tessl/npm-ecos@0.2.0

Entity Component System for JavaScript that enables component-based entity creation and management using a factory pattern

Guide: Creating Entities

This guide covers how to create entities using the ECOS factory system.

Basic Entity Creation

Step 1: Create a Factory

const { factory } = require('ecos');

const playerFactory = factory.create({
    name: 'player',              // Required: entity type
    props: ['name', 'level'],    // Properties to initialize
    default: { level: 1 }        // Default values
});

Step 2: Create Entities

const player1 = playerFactory.create({ name: 'Alice' });
// { type: 'player', name: 'Alice', level: 1, id: 0 }

const player2 = playerFactory.create({ name: 'Bob', level: 5 });
// { type: 'player', name: 'Bob', level: 5, id: 1 }

Factory Configuration Options

Minimal Factory

const minimalFactory = factory.create({
    name: 'simple'
});

const entity = minimalFactory.create();
// { type: 'simple', id: 0 }

Factory with Properties

const propsFactory = factory.create({
    name: 'item',
    props: ['name', 'value', 'weight']
});

const sword = propsFactory.create({ name: 'Sword', value: 100, weight: 5 });
// { type: 'item', name: 'Sword', value: 100, weight: 5, id: 0 }

Factory with Defaults

const defaultsFactory = factory.create({
    name: 'enemy',
    props: ['health', 'damage', 'speed'],
    default: {
        health: 100,
        damage: 10,
        speed: 5
    }
});

const goblin = defaultsFactory.create();
// { type: 'enemy', health: 100, damage: 10, speed: 5, id: 0 }

const boss = defaultsFactory.create({ health: 500, damage: 50 });
// { type: 'enemy', health: 500, damage: 50, speed: 5, id: 1 }

Entity Structure

All entities have:

id (number) - Auto-generated unique identifier
type (string) - Entity type (factory name)
Properties from factory configuration
Methods from factory configuration (see Using Methods)

Common Patterns

Pattern: Creating Multiple Similar Entities

const mobFactory = factory.create({
    name: 'mob',
    props: ['name', 'health', 'level'],
    default: { health: 50, level: 1 }
});

const mobs = [
    { name: 'Goblin', health: 50, level: 1 },
    { name: 'Orc', health: 100, level: 3 },
    { name: 'Troll', health: 200, level: 5 }
].map(data => mobFactory.create(data));

console.log(mobs);
// [
//   { type: 'mob', name: 'Goblin', health: 50, level: 1, id: 0 },
//   { type: 'mob', name: 'Orc', health: 100, level: 3, id: 1 },
//   { type: 'mob', name: 'Troll', health: 200, level: 5, id: 2 }
// ]

Pattern: Factory per Entity Type

// Organize factories by type
const factories = {
    player: factory.create({
        name: 'player',
        props: ['name', 'class', 'level'],
        default: { level: 1 }
    }),

    enemy: factory.create({
        name: 'enemy',
        props: ['name', 'health', 'damage'],
        default: { health: 100, damage: 10 }
    }),

    item: factory.create({
        name: 'item',
        props: ['name', 'type', 'value'],
        default: { value: 0 }
    })
};

// Use factories
const player = factories.player.create({ name: 'Hero', class: 'Warrior' });
const enemy = factories.enemy.create({ name: 'Goblin', health: 50 });
const item = factories.item.create({ name: 'Sword', type: 'weapon', value: 100 });

Pattern: Configuration-Based Entity Creation

const entityConfig = {
    player: {
        name: 'player',
        props: ['name', 'health', 'mana'],
        default: { health: 100, mana: 50 }
    },
    enemy: {
        name: 'enemy',
        props: ['name', 'health', 'damage'],
        default: { health: 50, damage: 10 }
    }
};

// Create factories from config
const factoryMap = {};
Object.entries(entityConfig).forEach(([key, config]) => {
    factoryMap[key] = factory.create(config);
});

// Use factories
const player = factoryMap.player.create({ name: 'Alice' });
const enemy = factoryMap.enemy.create({ name: 'Goblin' });

Accessing Created Entities

Entities are automatically stored in the entities container:

const { factory, entities } = require('ecos');

const itemFactory = factory.create({
    name: 'item',
    props: ['name']
});

const sword = itemFactory.create({ name: 'Sword' });
console.log(sword.id); // 0

// Retrieve from container
const retrieved = entities.get(sword.id);
console.log(retrieved === sword); // true
console.log(retrieved.name); // 'Sword'

📘 See Entities API Reference

Overriding Defaults

Values provided to create() override factory defaults:

const characterFactory = factory.create({
    name: 'character',
    props: ['name', 'health', 'mana', 'level'],
    default: {
        health: 100,
        mana: 50,
        level: 1
    }
});

// Use all defaults
const char1 = characterFactory.create({ name: 'Alice' });
// { name: 'Alice', health: 100, mana: 50, level: 1, ... }

// Override specific defaults
const char2 = characterFactory.create({ name: 'Bob', health: 150 });
// { name: 'Bob', health: 150, mana: 50, level: 1, ... }

// Override all defaults
const char3 = characterFactory.create({
    name: 'Charlie',
    health: 200,
    mana: 100,
    level: 10
});
// { name: 'Charlie', health: 200, mana: 100, level: 10, ... }

Property Initialization Order

Properties are initialized in this order:

Properties from props array (set to null initially)
Properties from default object (override nulls)
Properties from create(options) (override defaults)

const testFactory = factory.create({
    name: 'test',
    props: ['a', 'b', 'c'],
    default: { b: 'default-b', c: 'default-c' }
});

const entity = testFactory.create({ c: 'custom-c' });

console.log(entity.a); // null (from props, no default)
console.log(entity.b); // 'default-b' (from default)
console.log(entity.c); // 'custom-c' (from create options)

Complete Examples

Example: Game Entity System

const { factory, entities } = require('ecos');

// Define factories for different entity types
const playerFactory = factory.create({
    name: 'player',
    props: ['name', 'class', 'level', 'experience'],
    default: {
        level: 1,
        experience: 0
    }
});

const enemyFactory = factory.create({
    name: 'enemy',
    props: ['name', 'type', 'health', 'damage', 'loot'],
    default: {
        health: 50,
        damage: 5,
        loot: []
    }
});

const itemFactory = factory.create({
    name: 'item',
    props: ['name', 'type', 'value', 'effects'],
    default: {
        value: 0,
        effects: []
    }
});

// Create game entities
const player = playerFactory.create({
    name: 'Hero',
    class: 'Warrior'
});

const enemies = [
    enemyFactory.create({ name: 'Goblin', type: 'melee', health: 30 }),
    enemyFactory.create({ name: 'Archer', type: 'ranged', health: 25, damage: 8 }),
    enemyFactory.create({ name: 'Boss', type: 'boss', health: 200, damage: 20 })
];

const items = [
    itemFactory.create({ name: 'Health Potion', type: 'consumable', value: 25 }),
    itemFactory.create({ name: 'Sword', type: 'weapon', value: 100 }),
    itemFactory.create({ name: 'Shield', type: 'armor', value: 75 })
];

console.log(`Created ${entities.size()} entities`);
// Created 7 entities

// Access entities by ID
const firstEnemy = entities.get(enemies[0].id);
console.log(firstEnemy.name); // 'Goblin'

Example: Configuration-Driven Factory

const { factory } = require('ecos');

function createFactoryFromConfig(config) {
    return factory.create({
        name: config.type,
        props: config.properties,
        default: config.defaults || {}
    });
}

const configs = [
    {
        type: 'unit',
        properties: ['name', 'health', 'attack', 'defense'],
        defaults: { health: 100, attack: 10, defense: 5 }
    },
    {
        type: 'building',
        properties: ['name', 'health', 'produces'],
        defaults: { health: 500, produces: null }
    },
    {
        type: 'resource',
        properties: ['name', 'amount', 'maxAmount'],
        defaults: { amount: 0, maxAmount: 100 }
    }
];

const factoryInstances = configs.map(createFactoryFromConfig);

const unit = factoryInstances[0].create({ name: 'Soldier' });
const building = factoryInstances[1].create({ name: 'Barracks', produces: 'units' });
const resource = factoryInstances[2].create({ name: 'Gold', amount: 50 });

console.log(unit);     // { type: 'unit', name: 'Soldier', health: 100, attack: 10, defense: 5, id: 0 }
console.log(building); // { type: 'building', name: 'Barracks', health: 500, produces: 'units', id: 1 }
console.log(resource); // { type: 'resource', name: 'Gold', amount: 50, maxAmount: 100, id: 2 }

Next Steps

Using Methods - Add behavior to entities
Working with Extenders - Customize entity creation
Using Presets - Reuse configurations
Custom Constructors - Create specialized entity types

Version

tessl/npm-ecos

creating-entities.mddocs/guides/

Guide: Creating Entities

Basic Entity Creation

Step 1: Create a Factory

Step 2: Create Entities

Factory Configuration Options

Minimal Factory

Factory with Properties

Factory with Defaults

Entity Structure

Common Patterns

Pattern: Creating Multiple Similar Entities

Pattern: Factory per Entity Type

Pattern: Configuration-Based Entity Creation

Accessing Created Entities

Overriding Defaults

Property Initialization Order

Complete Examples

Example: Game Entity System

Example: Configuration-Driven Factory

Next Steps

See Also

Version

tessl/npm-ecos

creating-entities.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/guides/

Guide: Creating Entities

Basic Entity Creation

Step 1: Create a Factory

Step 2: Create Entities

Factory Configuration Options

Minimal Factory

Factory with Properties

Factory with Defaults

Entity Structure

Common Patterns

Pattern: Creating Multiple Similar Entities

Pattern: Factory per Entity Type

Pattern: Configuration-Based Entity Creation

Accessing Created Entities

Overriding Defaults

Property Initialization Order

Complete Examples

Example: Game Entity System

Example: Configuration-Driven Factory

Next Steps

See Also

creating-entities.mddocs/guides/