Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/NeonD00m/feces/llms.txt

Use this file to discover all available pages before exploring further.

The feces library exports three functions. new() initializes a feces instance bound to a jecs world. combine() merges delta changes into per-player packets. reserve() creates an entity group for namespace isolation.

​
feces.new(jecs, world, group?, debugPrints?)

Creates a new Feces instance that watches the supplied world for component changes and exposes apply, delta, full, and other helpers.
​
jecs
Jecs
required
The jecs module itself — pass the result of require(path.to.jecs).
​
world
World
required
A jecs.World extended with observer methods (added, changed, removed, deleted, monitor). All component tracking observers are registered on this world.
​
group
Group?
If provided, this feces instance uses the given group’s lookups and refs tables instead of creating its own. Useful for creating a client-side instance that mirrors a server-side reserved group.
​
debugPrints
boolean?
If true, feces prints internal debug messages via print(). Sets instance._debug.
Returns: Feces — the new feces instance.
feces.new() creates two internal components on the world — replicated and grouped — and registers world:added, world:changed, and world:removed observers for every component that already exists at call time. It also hooks world.component_index.__newindex so that any component created after new() is called is automatically tracked. A world:removed(replicated, ...) observer is installed to capture entity deletions for replication.For best results, create all your components before calling feces.new().
local jecs = require(path.to.jecs)
local feces = require(path.to.feces)

local world = jecs.world()
-- Create all components BEFORE calling feces.new()
local Transform = world:component()
local Health = world:component()

local instance = feces.new(jecs, world)

​
feces.combine(changes, deleted?)

Translates Changes and Deletes objects returned by instance:delta() into one Applyable packet per affected player, ready to be sent over a remote.
​
changes
Changes
required
The changes table returned by feces:delta().
​
deleted
Deletes?
The deletes table returned by feces:delta(). If omitted, no entity deletions are included in the resulting packets.
Returns: { [TestPlayer]: Applyable } — a table mapping each affected player (a Player instance or string identifier) to their per-player packet. Each Applyable contains all component changes and deletes for that player in one table, ready to send over a remote. Pass each value directly to remote:FireClient. 
local changes, deleted = instance:delta()
for player, packet in feces.combine(changes, deleted) do
    remote:FireClient(player, packet)
end
combine is also available on a feces instance as instance.combine (using the . operator), so you can call it without a separate reference to the library module.

​
feces.reserve(size, debugLocation?)

Creates a new Group — a separate entity lookup namespace. Groups are used to isolate replication to a bounded set of entities, and enable packing lookup IDs into a smaller number of bits.
​
size
number
required
The maximum number of entities this group should hold. A warning is emitted if this limit is exceeded.
​
debugLocation
boolean?
When true, uses debug.info to record the exact script and line where reserve() was called. This information is stored in group.origin and appears in warning messages. Useful for diagnosing which group overflowed.
Returns: Group — a new group table with empty lookups and refs tables and a recorded origin location for diagnostic messages.
Groups are used with instance:setGroup(), instance:delta(group), instance:full(group), and instance:apply(delta, group). See the Groups guide for a full walkthrough.
local dungeonGroup = feces.reserve(256)
You can also pass a reserved group directly to feces.new() to create an instance whose default namespace is that group: 
local group = feces.reserve(24)
local instance = feces.new(jecs, myWorld, group)
reserve is also available on a feces instance as instance.reserve (using the . operator).

Build docs developers (and LLMs) love

Get started for freeTalk to us