![]() |
Flecs v4.0
A fast entity component system (ECS) for C & C++
|
DSL for loading scenes, assets and configuration. More...
Classes | |
struct | ecs_script_var_t |
Script variable. More... | |
struct | ecs_script_vars_t |
Script variable scope. More... | |
struct | ecs_script_t |
Script object. More... | |
struct | EcsScript |
Script component. More... | |
struct | ecs_script_desc_t |
Used with ecs_script_init() More... | |
struct | ecs_script_expr_run_desc_t |
Used with ecs_script_expr_run(). More... | |
Macros | |
#define | FLECS_SCRIPT_H |
#define | ecs_script(world, ...) ecs_script_init(world, &(ecs_script_desc_t) __VA_ARGS__) |
#define | ecs_script_vars_define(vars, name, type) ecs_script_vars_define_id(vars, name, ecs_id(type)) |
Typedefs | |
typedef struct ecs_script_template_t | ecs_script_template_t |
typedef struct ecs_script_var_t | ecs_script_var_t |
Script variable. | |
typedef struct ecs_script_vars_t | ecs_script_vars_t |
Script variable scope. | |
typedef struct ecs_script_t | ecs_script_t |
Script object. | |
typedef struct EcsScript | EcsScript |
Script component. | |
typedef struct ecs_script_desc_t | ecs_script_desc_t |
Used with ecs_script_init() | |
typedef struct ecs_script_expr_run_desc_t | ecs_script_expr_run_desc_t |
Used with ecs_script_expr_run(). | |
Functions | |
FLECS_API | ECS_COMPONENT_DECLARE (EcsScript) |
FLECS_API ecs_script_t * | ecs_script_parse (ecs_world_t *world, const char *name, const char *code) |
Parse script. | |
FLECS_API int | ecs_script_eval (ecs_script_t *script) |
Evaluate script. | |
FLECS_API void | ecs_script_free (ecs_script_t *script) |
Free script. | |
FLECS_API int | ecs_script_run (ecs_world_t *world, const char *name, const char *code) |
Parse script. | |
FLECS_API int | ecs_script_run_file (ecs_world_t *world, const char *filename) |
Parse script file. | |
FLECS_API int | ecs_script_ast_to_buf (ecs_script_t *script, ecs_strbuf_t *buf) |
Convert script AST to string. | |
FLECS_API char * | ecs_script_ast_to_str (ecs_script_t *script) |
Convert script AST to string. | |
FLECS_API ecs_entity_t | ecs_script_init (ecs_world_t *world, const ecs_script_desc_t *desc) |
Load managed script. | |
FLECS_API int | ecs_script_update (ecs_world_t *world, ecs_entity_t script, ecs_entity_t instance, const char *code) |
Update script with new code. | |
FLECS_API void | ecs_script_clear (ecs_world_t *world, ecs_entity_t script, ecs_entity_t instance) |
Clear all entities associated with script. | |
FLECS_API ecs_script_vars_t * | ecs_script_vars_init (ecs_world_t *world) |
Create new variable scope. | |
FLECS_API void | ecs_script_vars_fini (ecs_script_vars_t *vars) |
Free variable scope. | |
FLECS_API ecs_script_vars_t * | ecs_script_vars_push (ecs_script_vars_t *parent) |
Push new variable scope. | |
FLECS_API ecs_script_vars_t * | ecs_script_vars_pop (ecs_script_vars_t *vars) |
Pop variable scope. | |
FLECS_API ecs_script_var_t * | ecs_script_vars_declare (ecs_script_vars_t *vars, const char *name) |
Declare a variable. | |
FLECS_API ecs_script_var_t * | ecs_script_vars_define_id (ecs_script_vars_t *vars, const char *name, ecs_entity_t type) |
Define a variable. | |
FLECS_API ecs_script_var_t * | ecs_script_vars_lookup (const ecs_script_vars_t *vars, const char *name) |
Lookup a variable. | |
FLECS_API void | ecs_script_vars_from_iter (const ecs_iter_t *it, ecs_script_vars_t *vars, int offset) |
Convert iterator to vars This operation converts an iterator to a variable array. | |
FLECS_API const char * | ecs_script_expr_run (ecs_world_t *world, const char *ptr, ecs_value_t *value, const ecs_script_expr_run_desc_t *desc) |
Parse standalone expression into value. | |
FLECS_API char * | ecs_script_string_interpolate (ecs_world_t *world, const char *str, const ecs_script_vars_t *vars) |
Evaluate interpolated expressions in string. | |
FLECS_API char * | ecs_ptr_to_expr (const ecs_world_t *world, ecs_entity_t type, const void *data) |
Serialize value into expression string. | |
FLECS_API int | ecs_ptr_to_expr_buf (const ecs_world_t *world, ecs_entity_t type, const void *data, ecs_strbuf_t *buf) |
Serialize value into expression buffer. | |
FLECS_API char * | ecs_ptr_to_str (const ecs_world_t *world, ecs_entity_t type, const void *data) |
Similar as ecs_ptr_to_expr(), but serializes values to string. | |
FLECS_API int | ecs_ptr_to_str_buf (const ecs_world_t *world, ecs_entity_t type, const void *data, ecs_strbuf_t *buf) |
Serialize value into string buffer. | |
FLECS_API void | FlecsScriptImport (ecs_world_t *world) |
Script module import function. | |
DSL for loading scenes, assets and configuration.
#define ecs_script | ( | world, | |
... ) ecs_script_init(world, &(ecs_script_desc_t) __VA_ARGS__) |
#define ecs_script_vars_define | ( | vars, | |
name, | |||
type ) ecs_script_vars_define_id(vars, name, ecs_id(type)) |
typedef struct EcsScript EcsScript |
Script component.
This component is added to the entities of managed scripts and templates.
FLECS_API char * ecs_ptr_to_expr | ( | const ecs_world_t * | world, |
ecs_entity_t | type, | ||
const void * | data ) |
Serialize value into expression string.
This operation serializes a value of the provided type to a string. The memory pointed to must be large enough to contain a value of the used type.
world | The world. |
type | The type of the value to serialize. |
data | The value to serialize. |
FLECS_API int ecs_ptr_to_expr_buf | ( | const ecs_world_t * | world, |
ecs_entity_t | type, | ||
const void * | data, | ||
ecs_strbuf_t * | buf ) |
Serialize value into expression buffer.
Same as ecs_ptr_to_expr(), but serializes to an ecs_strbuf_t instance.
world | The world. |
type | The type of the value to serialize. |
data | The value to serialize. |
buf | The strbuf to append the string to. |
FLECS_API char * ecs_ptr_to_str | ( | const ecs_world_t * | world, |
ecs_entity_t | type, | ||
const void * | data ) |
Similar as ecs_ptr_to_expr(), but serializes values to string.
Whereas the output of ecs_ptr_to_expr() is a valid expression, the output of ecs_ptr_to_str() is a string representation of the value. In most cases the output of the two operations is the same, but there are some differences:
world | The world. |
type | The type of the value to serialize. |
data | The value to serialize. |
FLECS_API int ecs_ptr_to_str_buf | ( | const ecs_world_t * | world, |
ecs_entity_t | type, | ||
const void * | data, | ||
ecs_strbuf_t * | buf ) |
Serialize value into string buffer.
Same as ecs_ptr_to_str(), but serializes to an ecs_strbuf_t instance.
world | The world. |
type | The type of the value to serialize. |
data | The value to serialize. |
buf | The strbuf to append the string to. |
FLECS_API int ecs_script_ast_to_buf | ( | ecs_script_t * | script, |
ecs_strbuf_t * | buf ) |
Convert script AST to string.
This operation converts the script abstract syntax tree to a string, which can be used to debug a script.
script | The script. |
buf | The buffer to write to. |
FLECS_API char * ecs_script_ast_to_str | ( | ecs_script_t * | script | ) |
Convert script AST to string.
This operation converts the script abstract syntax tree to a string, which can be used to debug a script.
script | The script. |
FLECS_API void ecs_script_clear | ( | ecs_world_t * | world, |
ecs_entity_t | script, | ||
ecs_entity_t | instance ) |
Clear all entities associated with script.
world | The world. |
script | The script entity. |
instance | The script instance. |
FLECS_API int ecs_script_eval | ( | ecs_script_t * | script | ) |
Evaluate script.
This operation evaluates (runs) a parsed script.
script | The script. |
FLECS_API const char * ecs_script_expr_run | ( | ecs_world_t * | world, |
const char * | ptr, | ||
ecs_value_t * | value, | ||
const ecs_script_expr_run_desc_t * | desc ) |
Parse standalone expression into value.
This operation parses a flecs expression into the provided pointer. The memory pointed to must be large enough to contain a value of the used type.
If no type and pointer are provided for the value argument, the operation will discover the type from the expression and allocate storage for the value. The allocated value must be freed with ecs_value_free().
world | The world. |
ptr | The pointer to the expression to parse. |
value | The value containing type & pointer to write to. |
desc | Configuration parameters for deserializer. |
FLECS_API void ecs_script_free | ( | ecs_script_t * | script | ) |
Free script.
This operation frees a script object.
Templates created by the script rely upon resources in the script object, and for that reason keep the script alive until all templates created by the script are deleted.
script | The script. |
FLECS_API ecs_entity_t ecs_script_init | ( | ecs_world_t * | world, |
const ecs_script_desc_t * | desc ) |
Load managed script.
A managed script tracks which entities it creates, and keeps those entities synchronized when the contents of the script are updated. When the script is updated, entities that are no longer in the new version will be deleted.
This feature is experimental.
world | The world. |
desc | Script descriptor. |
FLECS_API ecs_script_t * ecs_script_parse | ( | ecs_world_t * | world, |
const char * | name, | ||
const char * | code ) |
Parse script.
This operation parses a script and returns a script object upon success. To run the script, call ecs_script_eval().
world | The world. |
name | Name of the script (typically a file/module name). |
code | The script code. |
FLECS_API int ecs_script_run | ( | ecs_world_t * | world, |
const char * | name, | ||
const char * | code ) |
Parse script.
This parses a script and instantiates the entities in the world. This operation is the equivalent to doing:
world | The world. |
name | The script name (typically the file). |
code | The script. |
FLECS_API int ecs_script_run_file | ( | ecs_world_t * | world, |
const char * | filename ) |
Parse script file.
This parses a script file and instantiates the entities in the world. This operation is equivalent to loading the file contents and passing it to ecs_script_run().
world | The world. |
filename | The script file name. |
FLECS_API char * ecs_script_string_interpolate | ( | ecs_world_t * | world, |
const char * | str, | ||
const ecs_script_vars_t * | vars ) |
Evaluate interpolated expressions in string.
This operation evaluates expressions in a string, and replaces them with their evaluated result. Supported expression formats are:
The $, { and } characters can be escaped with a backslash ().
world | The world. |
str | The string to evaluate. |
vars | The variables to use for evaluation. |
FLECS_API int ecs_script_update | ( | ecs_world_t * | world, |
ecs_entity_t | script, | ||
ecs_entity_t | instance, | ||
const char * | code ) |
Update script with new code.
world | The world. |
script | The script entity. |
instance | An template instance (optional). |
code | The script code. |
FLECS_API ecs_script_var_t * ecs_script_vars_declare | ( | ecs_script_vars_t * | vars, |
const char * | name ) |
Declare a variable.
This operation declares a new variable in the current scope. If a variable with the specified name already exists, the operation will fail.
This operation does not allocate storage for the variable. This is done to allow for variables that point to existing storage, which prevents having to copy existing values to a variable scope.
vars | The variable scope. |
name | The variable name. |
FLECS_API ecs_script_var_t * ecs_script_vars_define_id | ( | ecs_script_vars_t * | vars, |
const char * | name, | ||
ecs_entity_t | type ) |
Define a variable.
This operation calls ecs_script_vars_declare()
and allocates storage for the variable. If the type has a ctor, it will be called on the new storage.
The scope's stack allocator will be used to allocate the storage. After ecs_script_vars_pop()
is called on the scope, the variable storage will no longer be valid.
The operation will fail if the type argument is not a type.
vars | The variable scope. |
name | The variable name. |
type | The variable type. |
FLECS_API void ecs_script_vars_fini | ( | ecs_script_vars_t * | vars | ) |
Free variable scope.
Free root variable scope. The provided scope should not have a parent. This operation calls ecs_script_vars_pop()
on the scope.
vars | The variable scope. |
FLECS_API void ecs_script_vars_from_iter | ( | const ecs_iter_t * | it, |
ecs_script_vars_t * | vars, | ||
int | offset ) |
Convert iterator to vars This operation converts an iterator to a variable array.
This allows for using iterator results in expressions. The operation only converts a single result at a time, and does not progress the iterator.
Iterator fields with data will be made available as variables with as name the field index (e.g. "$1"). The operation does not check if reflection data is registered for a field type. If no reflection data is registered for the type, using the field variable in expressions will fail.
Field variables will only contain single elements, even if the iterator returns component arrays. The offset parameter can be used to specify which element in the component arrays to return. The offset parameter must be smaller than it->count.
The operation will create a variable for query variables that contain a single entity.
The operation will attempt to use existing variables. If a variable does not yet exist, the operation will create it. If an existing variable exists with a mismatching type, the operation will fail.
Accessing variables after progressing the iterator or after the iterator is destroyed will result in undefined behavior.
If vars contains a variable that is not present in the iterator, the variable will not be modified.
it | The iterator to convert to variables. |
vars | The variables to write to. |
offset | The offset to the current element. |
FLECS_API ecs_script_vars_t * ecs_script_vars_init | ( | ecs_world_t * | world | ) |
Create new variable scope.
Create root variable scope. A variable scope contains one or more variables. Scopes can be nested, which allows variables in different scopes to have the same name. Variables from parent scopes will be shadowed by variables in child scopes with the same name.
Use the ecs_script_vars_push()
and ecs_script_vars_pop()
functions to push and pop variable scopes.
When a variable contains allocated resources (e.g. a string), its resources will be freed when ecs_script_vars_pop()
is called on the scope, the ecs_script_vars_t::type_info field is initialized for the variable, and ecs_type_info_t::hooks::dtor
is set.
world | The world. |
FLECS_API ecs_script_var_t * ecs_script_vars_lookup | ( | const ecs_script_vars_t * | vars, |
const char * | name ) |
Lookup a variable.
This operation looks up a variable in the current scope. If the variable can't be found in the current scope, the operation will recursively search the parent scopes.
vars | The variable scope. |
name | The variable name. |
FLECS_API ecs_script_vars_t * ecs_script_vars_pop | ( | ecs_script_vars_t * | vars | ) |
Pop variable scope.
This frees up the resources for a variable scope. The scope must be at the top of a vars stack. Calling ecs_script_vars_pop() on a scope that is not the last scope causes undefined behavior.
vars | The scope to free. |
FLECS_API ecs_script_vars_t * ecs_script_vars_push | ( | ecs_script_vars_t * | parent | ) |
Push new variable scope.
Scopes created with ecs_script_vars_push() must be cleaned up with ecs_script_vars_pop().
If the stack and allocator arguments are left to NULL, their values will be copied from the parent.
parent | The parent scope (provide NULL for root scope). |
FLECS_API void FlecsScriptImport | ( | ecs_world_t * | world | ) |