8000 GitHub - cloudwu/luaecs · GitHub
[go: up one dir, main page]

Skip to content
cloudwuPublic

About

No description, website, or topics provided.

Resources

Stars

349 stars

Watchers

16 watching

Forks

Latest commit

 

History

322 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Lua ECS

A simple Entity-Componet library for Lua.

-- Create a world
local w = ecs.world()

-- Register a new type "vector( x:float, y:float )" into world.
-- It's a C component (The data is in C memory).
w:register {
	name = "vector",
	"x:float",
	"y:float",
}

-- Register a new type "name" into world.
-- It's a Lua component (The value can be any lua object)
w:register {
	name = "name",
	type = "lua",
}

-- Create a new entity with components vector and name.
local eid = w:new {
	vector = { x = 1.0, y = 2.0 },
	name = "point",
}

-- Iterate every entity with component vector and name
for v in w:select "vector:in name:in" do
	-- v is the iterator, we can read compionent from it.
	-- DO NOT store v outside of the iteration
	print(v.name)	-- output : point
	print(v.vector.x, v.vector.y)	-- output: 1.0, 2.0
end

Component Types

C Component

The component is stored in C side, it's compat and can be accessed from C side easily. The supported buildin types are:

  • int (32bits)
  • float
  • bool (8bits)
  • int64
  • dword (unsigned 32bits)
  • word (unsigned 16bits)
  • byte (unsigned 8bits)
  • double
  • userdata (void *)
w:register {
	name = "vector",
	"x:float",
	"y:float",
}

The equivalent C struct is

struct vector {
	float x;
	float y;
};

A single buildin C type can be register as

w:register {
	name = "visible",
	type = "bool",
}

Lua component

The component is stored in Lua side , and can be any lua types, such as string, table, userdata, etc.

w:register {
	name = "name",
	type = "lua",
}

Tag

The tag is a special component , it can be read as a boolean type, and the value must be true. It used for selection.

w:register {
	name = "visible"
}

Entity ID

Each entity has a build-in readonly component eid , it's a 64bits unique monotonic ID. The newest entity always has the biggest eid.

Select Pattern

Use for v in world:select(pattern) to manage components. It iterate all the entities in the world and filter out the entities matching the pattern. The order of iteration is the creation order of the entities.

-- print all the entities' eid
for v in w:select "eid:in" do
	print(v.eid)
end

The pattern is a space-separated combination of componentname[:?]action, and the action can be

  • in : read the component
  • out : write the component
  • update : read / write
  • absent : check if the component is not exist
  • exist (default) : check if the component is exist
  • new : create the component
  • ? means it's an optional action if the component is not exist
-- clear temp component from all entities
w:clear "temp"

-- Iterate the entity with visible/value/output components and without readonly component
-- Create temp component for each.
for v in w:select "visible readonly:absent value:in output:out temp:new" do
	v.output = v.value + 1
	v.temp = v.value
end

NOTICE: If you use action new , you must guarantee the component is clear (None entity has this component) before iteration.

Create Entity

-- create an empty entity
local eid = w:new()
-- Import component "name" into entity (eid)
w:import(eid, { name = "foobar" })
-- Or you can use
local eid = w:new { name = "foobar" }

You can also create an entity from a template :

-- Create a template first
local t = w:template {
	name = "foobar"
}
-- instance the template into an entity, and add visible tag.
-- The additional components ( { visible = true } ) is optional.
local eid = w:template_instance(w:new(), t, { visible = true })

You can offer init / marshal / unmarshal functions for the component type in w:register().

marshal and unmarshal is for lua component of template, and init is the constructor of the component, the common use is for C component initialization.

NOTICE: C component can be initialize by a lua string, you can use string.pack() to generate the C structure data.

Remove Entity

8000
-- Remove an entity with eid
w:remove(eid)
-- Or remove an entity with an iterator
for v in w:select "value:in" do
	if v.value == 42 then
		w:remove(v)
	end
end

for v in w:select "REMOVED value:in do
	assert(v.value == 42)
end

-- delete all the entities removed
w:update()

The entities removed are not going to disppear immediately, they are tagged with REMOVED only, and deleted after you call w:update().

Group

You can add an entity into a group after creation. Each entity can belongs one or more groups (or no group).

-- Add entity (eid) into a group with groupid (32bit integer)
w:group_add(groupid, eid)

You can tags entities in groups with w:group_enable(groupid1, groupid2,...)

Persistance

Only C components can be persistance.

-- Save
-- Create a writer to file "saves.bin"
local writer = ecs.writer "saves.bin"
writer:write(w, w:component_id "eid") -- write component eid
writer:write(w, w:component_id "value") -- write component value
writer:write(w, w:component_id "tag") -- write component tag
local meta = writer:close()
local function print_section(s)
	print("offset =", s.offset)
	print("stride =", s.stride)
	print("n = ", s.n)
end
print_section(meta[1])	-- meta information of eid
print_section(meta[2])	-- meta information of value
print_section(meta[3])	-- meta information of tag
-- Load
local reader = ecs.reader "saves.bin"
local maxid = w:read_component(reader, "eid", meta[1].offset, meta[1].stride, meta[1].n)
local value_n = w:read_component(reader, "value", meta[2].offset, meta[2].stride, meta[2].n)
local tag_n = w:read_component(reader, "tag", meta[3].offset, meta[3].stride, meta[3].n)
reader:close()

You can also use w:generate_eid() instead of reading eid from file

Other APIs

w:exist(eid) -- Check if the entity with eid exist

w:clear(typename) -- delete component (typename) from all the entities

w:clearall() -- delete all the entities

w:component_id(typename) -- returns the component id of the component (typename) . It's for C systems.

w:type(typename) -- returns "tag", "lua" or "c"

w:first(pattern) -- Read the first component with the pattern.

w:filter(tagname, pattern) -- Enable tags marching the pattern

Access Components from C side

  1. Create a context by w:context { component1, component2, ... } for C. Export the components C concerned.
  2. Define C structs of components in C.
  3. Use APIs in luaecs.h

void * entity_iter(struct ecs_context *ctx, cid_t cid, int index) void * entity_sibling(struct ecs_context *ctx, cid_t cid, int index, cid_t sibling_id)

struct component *v;
int i;
// iterate all the components with COMPONENT_ID. COMPONENT_ID is the index of context (base 0) or component id from lua MAKE_COMPONENT_ID(cid)
for (i = 0; (v = (struct component *)entity_iter(ctx, COMPONENT_ID, i)); i++) {
	// Read the component2 associate with component (the same entity)
	struct component2 * c2 = (struct component2 *)entity_sibling(ctx, COMPONENT_ID, i, COMPONENT_ID2);
}

int entity_sibling_id(struct ecs_context *ctx, cid_t cid, int index, cid_t sibling_id)

The same with entity_sibling, but returns an id (base 1). 0 : not exist.

void * entity_add_sibling(struct ecs_context *ctx, cid_t cid, int index, cid_t sibling_id, const void *buffer)

int entity_new(struct ecs_context *ctx, cid_t cid, const void *buffer)

Create an entity with one component

void entity_remove(struct ecs_context *ctx, cid_t cid, int index)

void entity_enable_tag(struct ecs_context *ctx, cid_t cid, int index, cid_t tag_id)

void entity_disable_tag(struct ecs_context *ctx, cid_t cid, int index, cid_t tag_id)

int entity_get_lua(struct ecs_context *ctx, cid_t cid, int index, void *L) int entity_sibling_lua(struct ecs_context *ctx, cid_t cid, int index, cid_t sibling_id, void *L)

void entity_group_enable(struct ecs_context *ctx, int tagid, int n, int groupid[])

About

No description, website, or topics provided.

Resources

Stars

349 stars

Watchers

16 watching

Forks

Releases

Packages

Used by

Contributors

Languages

0