API Reference

Complete reference for the Beam API. Includes all methods and properties.

Color Legend

Blue Return types and return values
Coral Parameters and structure keys
Green Property references
Dark Red Method references

Methods

new

new: () -> world

Creates a new World instance, initializes core tables, and sets World.Singleton to the new instance.

Warning:

Call World.new() only once per session. Creating multiple worlds will overwrite World.Singleton and may orphan state.

Returns:

world World instance with initialized tables and systems

CraftEntity

CraftEntity: () -> number

Creates a new entity in the world, returning that entities id.

Returns:

number Entity ID - the unique identifier of the newly created entity

RegisterBody

RegisterBody: (Entity: number, Body: Instance) -> Instance?

Registers an entity-associated instance "Body", within Bodies, making it easier to retrieve entity id's. Returns the registered Body instance on success.

Warning:

Registering a Body that already exists will emit a warning, keep the original mapping, and return nil.

Returns:

Instance? The registered Body instance, or nil if the Body was already mapped

FetchBody

FetchBody: (Entity: number) -> Instance?

Retrieves the Instance body associated with a given entity ID from the Bodies table.

Returns:

Instance? The Instance associated with the entity, or nil if not found

Count

Count: (Components: { string }) -> string?

Returns the component, within a given table of components, which is associated with the smallest number of entities. Used: primarily for fast, mutli-component access; alongside ForEach

Returns:

string? Component name - the component with the smallest entity count, or nil if none

Kill

Kill: (Entity: number) -> ()

Destroys the specified entity.

ForEach

ForEach: (Entity: number, Components: { string }) -> (boolean, number?)

Iterates through Components, given an entity: and returns a boolean representing whether or not that entity has all the listed components. Depending on the case, returns an exit value

Returns:

tuple
boolean Success - whether the entity has all components
number? Exitcode - 0: no such event, 1: event found, entity not in event.

AssignComponent

AssignComponent: (Entity: number, Key: string, Data: { any }) -> ()

Given an entity, a key (name for the component) and the components data, stores a component and its data in Components.

UnassignComponent

UnassignComponent: (Entity: number, Key: string) -> ()

Removes a component from an entity by deleting it from the Components table.

AddSystem

AddSystem: (Module: ModuleScript, Priority: number?) -> ()

Adds a new system to the Systems table.

Warning:

Systems without an Update method are still registered but will never run. A warning is emitted at registration time.

Note:

The priority field determines the order of the required module instance within the sytems list. Systems are expected to include a .Update method. This method allows systems to be called each frame, in order, as the world loops through its systems table.

RemoveSystem

RemoveSystem: (Name: string) -> (boolean)

Removes a system from the Systems table. If the system has a valid Destroy method, it is called.

ReturnEntity

ReturnEntity: (Reference: Instance) -> number?

Returns the entity ID associated with a given Instance from the Bodies table.

Returns:

number? Entity ID - the entity associated with the instance, or nil if not found

FireEvent

FireEvent: (Event: event) -> ()

Fires an event to be processed in the next frame. The event is added to the Next event queue.

Warning:

Invalid event tables throw errors. Ensure Event is a string and Entity is a number.

Event Structure:

Event: string Required - The name of the event (traditionally camelCase)
Entity: number Required - The entity ID this event is associated with
Body: Instance? Optional - Instance reference associated with the event
Priority: number? Optional - Processing priority (higher = earlier, default: 0)

Example:

World.FireEvent({ Event = "take_damage", Entity = 5, Body = character, Priority = 10 })

Note:

Event names should follow snake_case convention (e.g., "take_damage", "player_died", "item_collected"). The Event and Entity fields are required; all other fields are optional but recommended for specific use cases.

ReadEntityEvent

ReadEntityEvent: (Entity: number, Name: string) -> (boolean, number?)

Checks if a specific entity has a fired event of the given name in the current Events table. This is useful for checking if an entity received a specific event in the current frame.

Returns:

tuple
boolean Found - whether the entity has the event in the current frame
number? Status code - 0 if no event with that name exists, 1 if event exists but entity not in it

ReadEvent

ReadEvent: (Name: string) -> { event }?

Returns the array of all events with a given name from the current Events table. Each event in the array is an event table containing Event, Entity, Body (optional), and Priority (optional) fields.

Returns:

{ event }? Array of event objects with that name, or nil if no events exist. Each event has Event (string), Entity (number), Body? (Instance), and Priority? (number) fields

Example:

local events = World.ReadEvent("take_damage") if events then for _, event in events do print("Entity:", event.Entity) print("Priority:", event.Priority or "default") end end

SubscribeTo

SubscribeTo: (Event: string, Callback: (Entity: number, Data: any) -> ()) -> ()

Calls the provided callback for each entity that has the specified event in the current Events table. The Event parameter should match the Event field of fired events (traditionally camelCase).

Callback Parameters:

Entity: number The entity ID associated with this event
Data: event table The full event object containing: Event (string), Entity (number), Body (Instance?), Priority (number?)

Example:

World.SubscribeTo("take_damage", function(entity, data) print("Entity", entity, "took damage!") print("Event:", data.Event) print("Body:", data.Body) print("Priority:", data.Priority) end)

Update

Update: (dt: number) -> ()

Updates all systems and processes events. Should be called once per game frame, normally by using RunService. Swaps Events with Next, then clears the Next queue.

Signals

Signals are fired automatically when specific actions occur in the world. Subscribe to them with the standard Signal API:

local connection = World.Crafted:Connect(function(EntityId) print("Entity created:", EntityId) end)

Crafted

Fired when a new entity is created via CraftEntity.

Crafted: Signal(EntityId: number)

Callback:

function(EntityId: number) -- The ID of the newly created entity

Killed

Fired when an entity is destroyed via Kill.

Killed: Signal(EntityId: number, RemovedCount: number)

Callback:

function(EntityId: number, RemovedCount: number)
-- EntityId: The ID of the entity being destroyed
-- RemovedCount: Number of components removed from the entity

AssignedComponent

Fired when a component is assigned to an entity via AssignComponent.

AssignedComponent: Signal(EntityId: number, Key: string, Data: any, Previous: any?)

Callback:

function(EntityId: number, Key: string, Data: any, Previous: any?)
-- EntityId: The ID of the entity receiving the component
-- Key: The component name/key
-- Data: The new component data
-- Previous: Previous component data if it existed, or nil if this is a new component

RemovedComponent

Fired when a component is removed from an entity via UnassignComponent or Kill.

RemovedComponent: Signal(EntityId: number, Key: string, Data: any)

Callback:

function(EntityId: number, Key: string, Data: any)
-- EntityId: The ID of the entity losing the component
-- Key: The component name/key
-- Data: The component data that was removed

Fired

Fired when an event is queued in the world via FireEvent.

Fired: Signal(EventName: string, EventPayload: event)

Callback:

function(EventName: string, EventPayload: event)
-- EventName: The name of the event being fired
-- EventPayload: The complete event table with Event, Entity, Body?, and Priority? fields

Properties

Components Read Only

A global table that stores all components for all entities. Components are organized by entity ID, then by component name.

Components: { [number]: { [string]: { any } } }

Structure:

[number]: table Entity ID mapped to its component table
[string]: table Component name mapped to its data

Example:

Components = { [1] = { Health = { hp = 100, max = 100 }, Position = { x = 5, y = 10 } }, [2] = { Velocity = { dx = 1, dy = 0 } } }

Note:

Use AssignComponent to add components and UnassignComponent to remove them. This table is the core of the ECS architecture.

Systems Read Only

An ordered list of registered systems, sorted by priority (higher runs earlier) and name as a tiebreaker.

Systems: { [number]: { Name: string, Instance: any, Priority: number } }

Structure:

[number]: table Array index mapped to a system entry
Name: string System name (ModuleScript name)
Instance: any Required module return (table with Update/Destroy)
Priority: number Execution priority (higher runs earlier)

Example:

Systems = { [1] = { Name = "Movement", Instance = MovementSystem, Priority = 100 }, [2] = { Name = "Damage", Instance = DamageSystem, Priority = 50 } }

Note:

Systems are added with AddSystem and removed with RemoveSystem. Each entry stores the required module result; if it exposes an Update method it will run each frame during Update. If a system has a Destroy method it is called on removal.

Bodies Read Only

A global table that maps Instance objects to their associated entity IDs. Uses weak keys for automatic cleanup.

Bodies: { [Instance]: number }

Structure:

[Instance]: number Instance reference mapped to entity ID

Note:

This table uses weak keys, meaning when an Instance is destroyed, the entry is automatically cleaned up. Use ReturnEntity to look up entity IDs by Instance.

Alive Read Only

A global table that tracks which entities are currently alive in the world.

Alive: { [number]: boolean }

Structure:

[number]: boolean Entity ID mapped to alive status (true = alive, nil = dead)

Note:

When an entity is killed via Kill, its entry is removed from this table. Check this table to determine if an entity is still active.

Events Read Only

A global table containing the current frame's events. Each event name maps to a bucket of all events with that name.

Events: { [string]: { event } }

Structure:

[string]: array Event name mapped to array of events
[number]: event Entity ID mapped to individual event object

Example:

Events = { ["take_damage"] = { [1] = { Event = "take_damage", Entity = 1, Body = part1, Priority = 10 }, [2] = { Event = "take_damage", Entity = 2, Body = part2, Priority = 5 } }, ["player_died"] = { [3] = { Event = "player_died", Entity = 3, Priority = 20 } } }

Note:

The Events table is swapped with Next during each Update call. Event names should follow snake_case convention. Each event must have an Event (name) and Entity field. See FireEvent for complete event structure requirements.

Next Read Only

A global table containing events queued for the next frame. Events are added here via FireEvent.

Next: { [string]: { event } }

Structure:

[string]: array Event name mapped to array of queued events
[number]: event Entity ID mapped to individual event object

Note:

This table becomes the Events table during the next Update call. The current Events table then becomes Next. All events must conform to the structure defined in FireEvent.

Internals

Singleton Read Only

The singleton instance of the World. Stores the current active World object for global access.

Singleton: world?

Note:

This is set automatically when a new World is created via World.new(). It provides a global reference to the active World instance, allowing other systems to access the world without explicit parameter passing.