Flecs
v4.1
Flecs
v4.1
DSL for loading scenes, assets, and configuration. More...
Macros | |
| #define | FLECS_SCRIPT_H |
| #define | FLECS_SCRIPT_FUNCTION_ARGS_MAX (16) |
| #define | FLECS_SCRIPT_VECTOR_FUNCTION_COUNT (18) |
| #define | ecs_script(world, ...) |
| #define | ecs_script_vars_define(vars, name, type) |
| #define | ecs_const_var(world, ...) |
| #define | ecs_const_var_get_t(world, name, T) |
| Return pointer to the value of a const variable. | |
| #define | ecs_mut_var(world, ...) |
| #define | ecs_mut_var_get_t(world, name, T) |
| Return pointer to the value of a mut variable. | |
| #define | ecs_mut_var_set_t(world, name, T, ...) |
| Set the value of a mut variable. | |
| #define | ecs_function(world, ...) |
| #define | ecs_method(world, ...) |
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 ecs_script_runtime_t | ecs_script_runtime_t |
| Runtime for executing scripts. | |
| typedef struct EcsScript | EcsScript |
| Script component. | |
| typedef struct ecs_function_ctx_t | ecs_function_ctx_t |
| Script function context. | |
| typedef void(*) | ecs_function_callback_t(const ecs_function_ctx_t *ctx, int32_t argc, const ecs_value_t *argv, ecs_value_t *result) |
| Script function callback. | |
| typedef void(*) | ecs_vector_function_callback_t(const ecs_function_ctx_t *ctx, int32_t argc, const ecs_value_t *argv, ecs_value_t *result, int32_t elem_count) |
| Script vector function callback. | |
| typedef struct ecs_script_parameter_t | ecs_script_parameter_t |
| Function argument type. | |
| typedef struct ecs_script_eval_desc_t | ecs_script_eval_desc_t |
| Used with ecs_script_parse() and ecs_script_eval(). | |
| typedef struct ecs_script_eval_result_t | ecs_script_eval_result_t |
| Used to capture error output from script evaluation. | |
| typedef struct EcsScriptConstVar | EcsScriptConstVar |
| Const component. | |
| typedef struct EcsScriptMutVar | EcsScriptMutVar |
| Mut component. | |
| typedef struct ecs_script_function_t | EcsScriptFunction |
| Function component. | |
| typedef struct ecs_script_function_t | EcsScriptMethod |
| Method component. | |
| typedef struct ecs_script_source_t | ecs_script_source_t |
| Source location of a script statement. | |
| typedef struct ecs_script_edits_t | ecs_script_edits_t |
| Set of pending edits for a script. | |
| typedef struct ecs_script_desc_t | ecs_script_desc_t |
| Used with ecs_script_init(). | |
| typedef struct ecs_expr_eval_desc_t | ecs_expr_eval_desc_t |
| Used with ecs_expr_run(). | |
| typedef struct ecs_const_var_desc_t | ecs_const_var_desc_t |
| Used with ecs_const_var_init(). | |
| typedef struct ecs_mut_var_desc_t | ecs_mut_var_desc_t |
| Used with ecs_mut_var_init(). | |
| typedef struct ecs_vector_fn_callbacks_t | ecs_vector_fn_callbacks_t |
| Vector function callbacks for different element types. | |
| typedef struct ecs_function_desc_t | ecs_function_desc_t |
| Used with ecs_function_init() and ecs_method_init(). | |
| typedef struct ecs_expr_node_t | ecs_expr_node_t |
Functions | |
| FLECS_API | ECS_COMPONENT_DECLARE (EcsScript) |
| FLECS_API | ECS_DECLARE (EcsScriptTemplate) |
| FLECS_API | ECS_DECLARE (EcsScriptTemplateManual) |
| FLECS_API | ECS_DECLARE (EcsScriptTemplatePending) |
| FLECS_API int | ecs_script_template_update (ecs_world_t *world, ecs_entity_t instance, ecs_entity_t template_entity) |
| FLECS_API | ECS_COMPONENT_DECLARE (EcsScriptConstVar) |
| FLECS_API | ECS_COMPONENT_DECLARE (EcsScriptMutVar) |
| FLECS_API | ECS_COMPONENT_DECLARE (EcsScriptFunction) |
| FLECS_API | ECS_DECLARE (EcsScriptVectorType) |
| FLECS_API ecs_script_t * | ecs_script_parse (ecs_world_t *world, const char *name, const char *code, const ecs_script_eval_desc_t *desc, ecs_script_eval_result_t *result) |
| Parse script. | |
| FLECS_API int | ecs_script_eval (const ecs_script_t *script, const ecs_script_eval_desc_t *desc, ecs_script_eval_result_t *result) |
| 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, ecs_script_eval_result_t *result) |
| Parse script. | |
| FLECS_API int | ecs_script_run_w_desc (ecs_world_t *world, const char *name, const char *code, const ecs_script_eval_desc_t *desc, ecs_script_eval_result_t *result) |
| Parse script and evaluate with options. | |
| FLECS_API int | ecs_script_run_file (ecs_world_t *world, const char *filename) |
| Parse script file. | |
| FLECS_API int | ecs_script_run_file_w_desc (ecs_world_t *world, const char *filename, const ecs_script_eval_desc_t *desc) |
| Parse script file and evaluate with options. | |
| FLECS_API char * | ecs_script_ir_to_str (const ecs_script_t *script) |
| Convert script IR to string. | |
| FLECS_API ecs_script_runtime_t * | ecs_script_runtime_new (void) |
| Create runtime for script. | |
| FLECS_API void | ecs_script_runtime_free (ecs_script_runtime_t *runtime) |
| Free script runtime. | |
| FLECS_API int | ecs_script_ast_to_buf (ecs_script_t *script, ecs_strbuf_t *buf, bool colors) |
| Convert script AST to string. | |
| FLECS_API char * | ecs_script_ast_to_str (ecs_script_t *script, bool colors) |
| Convert script AST to string. | |
| FLECS_API bool | ecs_script_entity_source (const ecs_script_t *script, ecs_entity_t entity, ecs_script_source_t *source) |
| Find the statement that declares an entity. | |
| FLECS_API ecs_entity_t | ecs_script_entity_owner (const ecs_world_t *world, ecs_entity_t entity) |
| Find the managed script that declares an entity. | |
| FLECS_API ecs_script_edits_t * | ecs_script_edits_new (ecs_script_t *script) |
| Create an edit set for a script. | |
| FLECS_API void | ecs_script_edits_free (ecs_script_edits_t *edits) |
| Free an edit set. | |
| FLECS_API int | ecs_script_edits_set (ecs_script_edits_t *edits, ecs_entity_t entity, ecs_id_t component, const void *value) |
| Set a component value on an entity. | |
| FLECS_API int | ecs_script_edits_set_expr (ecs_script_edits_t *edits, ecs_entity_t entity, ecs_id_t component, const char *expr) |
| Set a component value on an entity from an expression string. | |
| FLECS_API int | ecs_script_edits_remove (ecs_script_edits_t *edits, ecs_entity_t entity, ecs_id_t component) |
| Remove a component from an entity. | |
| FLECS_API int | ecs_script_edits_delete (ecs_script_edits_t *edits, ecs_entity_t entity) |
| Delete an entity. | |
| FLECS_API int | ecs_script_edits_clear (ecs_script_edits_t *edits, ecs_entity_t entity, ecs_id_t component) |
| Remove a recorded edit from an edit set. | |
| FLECS_API int32_t | ecs_script_edits_count (const ecs_script_edits_t *edits) |
| Return the number of recorded edits in an edit set. | |
| FLECS_API char * | ecs_script_edits_apply (const ecs_script_edits_t *edits) |
| Apply an edit set. | |
| 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 ecs_script_var_t * | ecs_script_vars_from_sp (const ecs_script_vars_t *vars, int32_t sp) |
| Lookup a variable by stack pointer. | |
| FLECS_API void | ecs_script_vars_print (const ecs_script_vars_t *vars) |
| Print variables. | |
| FLECS_API void | ecs_script_vars_set_size (ecs_script_vars_t *vars, int32_t count) |
| Preallocate space for variables. | |
| FLECS_API void | ecs_script_vars_from_iter (const ecs_iter_t *it, ecs_script_vars_t *vars, int offset) |
| Convert iterator to vars. | |
| FLECS_API const char * | ecs_expr_run (ecs_world_t *world, const char *ptr, ecs_value_t *value, const ecs_expr_eval_desc_t *desc) |
| Run expression. | |
| FLECS_API ecs_script_t * | ecs_expr_parse (ecs_world_t *world, const char *expr, const ecs_expr_eval_desc_t *desc) |
| Parse expression. | |
| FLECS_API int | ecs_expr_eval (const ecs_script_t *script, ecs_value_t *value, const ecs_expr_eval_desc_t *desc) |
| Evaluate expression. | |
| 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 ecs_entity_t | ecs_const_var_init (ecs_world_t *world, ecs_const_var_desc_t *desc) |
| Create a const variable that can be accessed by scripts. | |
| FLECS_API ecs_value_t | ecs_const_var_get (const ecs_world_t *world, ecs_entity_t var) |
| Return the value for a const variable. | |
| FLECS_API void * | ecs_const_var_get_w_type (const ecs_world_t *world, const char *name, ecs_entity_t type, ecs_size_t size, void *out) |
| Return pointer to the value of a const variable. | |
| FLECS_API ecs_entity_t | ecs_mut_var_init (ecs_world_t *world, ecs_mut_var_desc_t *desc) |
| Create a mut variable that can be accessed by scripts. | |
| FLECS_API ecs_value_t | ecs_mut_var_get (const ecs_world_t *world, ecs_entity_t var) |
| Return the value for a mut variable. | |
| FLECS_API void * | ecs_mut_var_get_w_type (const ecs_world_t *world, const char *name, ecs_entity_t type, ecs_size_t size, void *out) |
| Return pointer to the value of a mut variable. | |
| FLECS_API int | ecs_mut_var_set_w_type (ecs_world_t *world, const char *name, ecs_entity_t type, ecs_size_t size, const void *value) |
| Set the value of a mut variable. | |
| FLECS_API void | ecs_mut_var_modified (ecs_world_t *world, ecs_entity_t var) |
| Mark mut var as modified. | |
| FLECS_API ecs_entity_t | ecs_function_init (ecs_world_t *world, const ecs_function_desc_t *desc) |
| Create new function. | |
| FLECS_API int | ecs_function_call (ecs_world_t *world, ecs_entity_t function, int32_t argc, const ecs_value_t *argv, ecs_value_t *result) |
| FLECS_API ecs_entity_t | ecs_method_init (ecs_world_t *world, const ecs_function_desc_t *desc) |
| Create new method. | |
| FLECS_API int | ecs_method_call (ecs_world_t *world, ecs_entity_t method, const ecs_value_t *instance, int32_t argc, const ecs_value_t *argv, ecs_value_t *result) |
| 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 to 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_const_var | ( | world, | |
| ... ) |
| #define ecs_const_var_get_t | ( | world, | |
| name, | |||
| T ) |
Return pointer to the value of a const variable.
This operation returns the value of a const variable, casted to the specified type. If the type is equal to that of the const variable, no cast is performed. If the variable cannot be casted to the specified type, the operation will throw an error.
The returned value is owned by the caller. If the returned value contains allocated memory, this needs to be freed by the caller.
When the operation fails, a zero initialized value is returned.
| world | The world. |
| name | The name of the const variable. |
| T | The requested type. |
| #define ecs_function | ( | world, | |
| ... ) |
| #define ecs_method | ( | world, | |
| ... ) |
| #define ecs_mut_var | ( | world, | |
| ... ) |
| #define ecs_mut_var_get_t | ( | world, | |
| name, | |||
| T ) |
Return pointer to the value of a mut variable.
This operation returns the value of a mut variable, casted to the specified type. If the type is equal to that of the mut variable, no cast is performed. If the variable cannot be casted to the specified type, the operation will throw an error.
The returned value is owned by the caller. If the returned value contains allocated memory, this needs to be freed by the caller.
When the operation fails, a zero initialized value is returned.
| world | The world. |
| name | The name of the mut variable. |
| T | The requested type. |
| #define ecs_mut_var_set_t | ( | world, | |
| name, | |||
| T, | |||
| ... ) |
Set the value of a mut variable.
This operation sets the value of a mut variable from a value of the specified type. If the type is equal to that of the mut variable, no cast is performed. If the value cannot be casted to the type of the mut variable, the operation will throw an error.
The provided value is copied into the storage of the mut variable and does not need to be kept alive.
On success, OnSet observers for the mut variable are notified, which causes scripts that use the variable to be reevaluated.
| world | The world. |
| name | The name of the mut variable. |
| T | The type of the provided value. |
| #define ecs_script | ( | world, | |
| ... ) |
| #define ecs_script_vars_define | ( | vars, | |
| name, | |||
| type ) |
| typedef void(*) ecs_function_callback_t(const ecs_function_ctx_t *ctx, int32_t argc, const ecs_value_t *argv, ecs_value_t *result) |
| typedef struct ecs_script_edits_t ecs_script_edits_t |
Set of pending edits for a script.
| typedef struct ecs_script_runtime_t ecs_script_runtime_t |
| typedef struct ecs_script_source_t ecs_script_source_t |
Source location of a script statement.
Returned by ecs_script_entity_source(). The offset and length are byte offsets into ecs_script_t::code.
| typedef void(*) ecs_vector_function_callback_t(const ecs_function_ctx_t *ctx, int32_t argc, const ecs_value_t *argv, ecs_value_t *result, int32_t elem_count) |
| typedef struct EcsScript EcsScript |
Script component.
This component is added to the entities of managed scripts and templates.
| typedef struct EcsScriptConstVar EcsScriptConstVar |
Const component.
This component describes a const variable that can be used from scripts. The value of a const variable is folded into expressions that use it.
| typedef struct ecs_script_function_t EcsScriptFunction |
| typedef struct ecs_script_function_t EcsScriptMethod |
| typedef struct EcsScriptMutVar EcsScriptMutVar |
Mut component.
This component describes a mutable global variable that can be used from scripts. Unlike a const variable, the value of a mut variable is never folded into expressions, and scripts that use it are reevaluated when it changes.
| FLECS_API ecs_value_t ecs_const_var_get | ( | const ecs_world_t * | world, |
| ecs_entity_t | var ) |
Return the value for a const variable.
This returns the value for a const variable that is created either with ecs_const_var_init(), or in a script with "export const v = ...".
| world | The world. |
| var | The const variable. |
| FLECS_API void * ecs_const_var_get_w_type | ( | const ecs_world_t * | world, |
| const char * | name, | ||
| ecs_entity_t | type, | ||
| ecs_size_t | size, | ||
| void * | out ) |
Return pointer to the value of a const variable.
This operation returns the value of a const variable, casted to the specified type. If the type is equal to that of the const variable, no cast is performed. If the variable cannot be casted to the specified type, the operation will throw an error.
The returned value is owned by the caller. If the returned value contains allocated memory, this needs to be freed by the caller.
This operation is intended to be used by the ecs_const_var_get_t macro.
| world | The world. |
| name | The name of the const variable. |
| type | The requested type. |
| size | The size of the requested type. |
| out | Storage for the value of the const variable. |
| FLECS_API ecs_entity_t ecs_const_var_init | ( | ecs_world_t * | world, |
| ecs_const_var_desc_t * | desc ) |
Create a const variable that can be accessed by scripts.
| world | The world. |
| desc | Const var parameters. |
| FLECS_API int ecs_expr_eval | ( | const ecs_script_t * | script, |
| ecs_value_t * | value, | ||
| const ecs_expr_eval_desc_t * | desc ) |
Evaluate expression.
This operation evaluates an expression parsed with ecs_expr_parse() and stores the result in the provided value. If the value contains a type that is different from the type of the expression, the expression will be cast to the value.
If the provided value for value.ptr is NULL, the value must be freed with ecs_ptr_free() afterwards.
| script | The script containing the expression. |
| value | The value in which to store the expression result. |
| desc | Configuration parameters for the parser. |
| FLECS_API ecs_script_t * ecs_expr_parse | ( | ecs_world_t * | world, |
| const char * | expr, | ||
| const ecs_expr_eval_desc_t * | desc ) |
Parse expression.
This operation parses an expression and returns an object that can be evaluated multiple times with ecs_expr_eval().
| world | The world. |
| expr | The expression string. |
| desc | Configuration parameters for the parser. |
| FLECS_API const char * ecs_expr_run | ( | ecs_world_t * | world, |
| const char * | ptr, | ||
| ecs_value_t * | value, | ||
| const ecs_expr_eval_desc_t * | desc ) |
Run expression.
This operation runs an expression and stores the result in the provided value. If the value contains a type that is different from the type of the expression, the expression will be cast to the value.
If the provided value for value.ptr is NULL, the value must be freed with ecs_ptr_free() afterwards.
| world | The world. |
| ptr | The pointer to the expression to parse. |
| value | The value containing type and pointer to write to. |
| desc | Configuration parameters for the parser. |
| FLECS_API ecs_entity_t ecs_function_init | ( | ecs_world_t * | world, |
| const ecs_function_desc_t * | desc ) |
Create new function.
This operation creates a new function that can be called from a script.
| world | The world. |
| desc | Function init parameters. |
| FLECS_API ecs_entity_t ecs_method_init | ( | ecs_world_t * | world, |
| const ecs_function_desc_t * | desc ) |
Create new method.
This operation creates a new method that can be called from a script. A method is like a function, except that it can be called on every instance of a type.
Methods automatically receive the instance on which the method is invoked as first argument.
| world | The world. |
| desc | Method init parameters. |
| FLECS_API ecs_value_t ecs_mut_var_get | ( | const ecs_world_t * | world, |
| ecs_entity_t | var ) |
Return the value for a mut variable.
This returns the value for a mut variable that is created either with ecs_mut_var_init(), or in a script with "export mut v = ...".
| world | The world. |
| var | The mut variable. |
| FLECS_API void * ecs_mut_var_get_w_type | ( | const ecs_world_t * | world, |
| const char * | name, | ||
| ecs_entity_t | type, | ||
| ecs_size_t | size, | ||
| void * | out ) |
Return pointer to the value of a mut variable.
This operation returns the value of a mut variable, casted to the specified type. If the type is equal to that of the mut variable, no cast is performed. If the variable cannot be casted to the specified type, the operation will throw an error.
The returned value is owned by the caller. If the returned value contains allocated memory, this needs to be freed by the caller.
This operation is intended to be used by the ecs_mut_var_get_t macro.
| world | The world. |
| name | The name of the mut variable. |
| type | The requested type. |
| size | The size of the requested type. |
| out | Storage for the value of the mut variable. |
| FLECS_API ecs_entity_t ecs_mut_var_init | ( | ecs_world_t * | world, |
| ecs_mut_var_desc_t * | desc ) |
Create a mut variable that can be accessed by scripts.
Unlike a const variable the value of a mut variable is never folded into expressions, which means scripts that use it are reevaluated when the value changes.
| world | The world. |
| desc | Mut var parameters. |
| FLECS_API void ecs_mut_var_modified | ( | ecs_world_t * | world, |
| ecs_entity_t | var ) |
Mark mut var as modified.
This will notify OnSet observers.
| world | The world. |
| var | The mut variable. |
| FLECS_API int ecs_mut_var_set_w_type | ( | ecs_world_t * | world, |
| const char * | name, | ||
| ecs_entity_t | type, | ||
| ecs_size_t | size, | ||
| const void * | value ) |
Set the value of a mut variable.
This operation sets the value of a mut variable from a value of the specified type. If the type is equal to that of the mut variable, no cast is performed. If the value cannot be casted to the type of the mut variable, the operation will throw an error.
The provided value is copied into the storage of the mut variable and does not need to be kept alive.
On success, OnSet observers for the mut variable are notified, which causes scripts that use the variable to be reevaluated.
This operation is intended to be used by the ecs_mut_var_set_t macro.
| world | The world. |
| name | The name of the mut variable. |
| type | The type of the provided value. |
| size | The size of the provided type. |
| value | Pointer to the value to set. |
| 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 to 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, | ||
| bool | colors ) |
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. |
| colors | Whether to include ANSI color codes in the output. |
| FLECS_API char * ecs_script_ast_to_str | ( | ecs_script_t * | script, |
| bool | colors ) |
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. |
| colors | Whether to include ANSI color codes in the output. |
| 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 char * ecs_script_edits_apply | ( | const ecs_script_edits_t * | edits | ) |
Apply an edit set.
This operation returns new script source code with the edits applied. The operation does not modify the script or the edit set, which means that applying the same edit set twice returns the same text.
The operation returns NULL when two edits overlap in a way that cannot be resolved.
| edits | The edit set. |
| FLECS_API int ecs_script_edits_clear | ( | ecs_script_edits_t * | edits, |
| ecs_entity_t | entity, | ||
| ecs_id_t | component ) |
Remove a recorded edit from an edit set.
Edits are keyed by entity and component. This operation removes the edit that was recorded for the provided key, which undoes the effect that the edit would have had on ecs_script_edits_apply().
Pass 0 for the component to clear the edit recorded by ecs_script_edits_delete(). Pass a component (or pair) to clear the edit recorded by ecs_script_edits_set(), ecs_script_edits_set_expr() or ecs_script_edits_remove() for that component.
The entity is only used as a key. It does not have to be alive, which means an edit that was recorded before the entity was deleted can still be cleared afterwards.
| edits | The edit set. |
| entity | The entity the edit was recorded for. |
| component | The component the edit was recorded for, or 0 for a delete. |
| FLECS_API int32_t ecs_script_edits_count | ( | const ecs_script_edits_t * | edits | ) |
Return the number of recorded edits in an edit set.
Edits are keyed by entity and component, which means that recording an edit twice for the same key does not increase the count.
| edits | The edit set. |
| FLECS_API int ecs_script_edits_delete | ( | ecs_script_edits_t * | edits, |
| ecs_entity_t | entity ) |
Delete an entity.
This removes the entity statement, its scope, and the line(s) the statement occupies. Comments that precede the statement are preserved. A trailing comment on the last line of the statement is removed together with the line.
When the removed lines are surrounded by blank lines (where the start of the file, the opening brace of the enclosing scope, the closing brace of the enclosing scope and the end of the file count as blank), one of the blank lines is removed as well, so that the statements around the deleted statement stay separated by exactly one blank line.
Other edits that fall inside the span of a deleted entity (such as edits to child entities) are absorbed by the deletion.
When the entity was created by a template body statement (see ecs_script_entity_source()) the statement in the template body is deleted, which removes the entity from every instance of the template.
The operation only records the source code span of the statement, it does not delete the entity. The edit must be recorded while the entity is still alive; the recorded edit remains valid after the entity is deleted with ecs_delete(). See ecs_script_edits_new().
| edits | The edit set. |
| entity | The entity to delete. |
| FLECS_API void ecs_script_edits_free | ( | ecs_script_edits_t * | edits | ) |
Free an edit set.
| edits | The edit set. |
| FLECS_API ecs_script_edits_t * ecs_script_edits_new | ( | ecs_script_t * | script | ) |
Create an edit set for a script.
An edit set collects changes that are keyed by entity id, and turns them into new script source code with ecs_script_edits_apply(). Only the edited statements change; all other text (comments, whitespace, layout, expressions, include statements) is preserved byte for byte.
The script must be evaluated before edits can be added, and must outlive the edit set.
Edits are resolved to a source code span when they are recorded, not when they are applied. The entity is only used to find the statement at that moment; afterwards the recorded edit no longer depends on it. This means an edit set can outlive the entities it was recorded for, but it also means that a delete must be recorded before the entity is deleted:
Recording an edit for an entity that is no longer alive fails, as the statement can no longer be found.
A recorded edit can be dropped again with ecs_script_edits_clear(), which makes it possible to use a single edit set as an undo/redo buffer for an editing session.
An edit set must be deleted with ecs_script_edits_free().
| script | The script to edit. |
| FLECS_API int ecs_script_edits_remove | ( | ecs_script_edits_t * | edits, |
| ecs_entity_t | entity, | ||
| ecs_id_t | component ) |
Remove a component from an entity.
This removes the statement that adds the component (or tag) to the entity, including the line(s) the statement occupies. If the entity scope contains more than one statement for the component, the last statement is removed.
The operation returns zero when the entity does not have a statement for the component, as the resulting source has the requested state.
| edits | The edit set. |
| entity | The entity to edit. |
| component | The component (or pair) to remove. |
| FLECS_API int ecs_script_edits_set | ( | ecs_script_edits_t * | edits, |
| ecs_entity_t | entity, | ||
| ecs_id_t | component, | ||
| const void * | value ) |
Set a component value on an entity.
If the entity scope already contains a statement for the component, only the value expression of that statement is replaced. The style of the existing initializer is preserved:
All members of the component are written, in the order in which they are defined by the type. Floating point members are written as the shortest decimal string that parses back to the same value ("1.2345" for a float with value 1.2345f, "1" for a float with value 1.0f), so values roundtrip without accumulating digits.
When the entity was created by a template body statement (see ecs_script_entity_source()) the statement in the template body is edited, which changes the value for every instance of the template. Any expression that the body used for the value (such as a prop or const reference) is replaced by the literal value that is passed to this operation.
If the entity scope does not contain a statement for the component, a new "Component: {...}" statement is appended to the end of the entity scope, using the indentation of the other statements in the scope (or the indentation of the entity statement plus four spaces when the scope is empty). When the entity statement has no scope, a scope is added.
If the entity scope contains more than one statement for the component, the last statement is replaced. If the entity is declared by more than one statement, the first declaration is edited.
Only statements in the scope of the entity itself are considered. A value that the entity inherits from an enclosing with statement is not modified; setting such a component adds a statement to the entity scope that overrides the with value.
The component is written with the shortest name that resolves to the same component given the using and module statements of the script.
| edits | The edit set. |
| entity | The entity to edit. |
| component | The component (or pair) to set. |
| value | Pointer to the component value. |
| FLECS_API int ecs_script_edits_set_expr | ( | ecs_script_edits_t * | edits, |
| ecs_entity_t | entity, | ||
| ecs_id_t | component, | ||
| const char * | expr ) |
Set a component value on an entity from an expression string.
Same as ecs_script_edits_set(), but instead of serializing a value, the provided expression is written to the script verbatim. The expression is not validated.
| edits | The edit set. |
| entity | The entity to edit. |
| component | The component (or pair) to set. |
| expr | The value expression (for example "{10, 20}"). |
| FLECS_API ecs_entity_t ecs_script_entity_owner | ( | const ecs_world_t * | world, |
| ecs_entity_t | entity ) |
Find the managed script that declares an entity.
This operation returns the entity of the managed script (see ecs_script()) whose source code contains the statement that created the entity. The returned script entity is the one to use with ecs_script_entity_source() and ecs_script_edits_new():
For entities that were created by a regular entity statement this is the script that created the entity. For entities that were created by a template body this is the script that declares the template, which is not necessarily the script that instantiates it.
The operation returns 0 when the entity is not editable, which is the case when the entity was not created by a script, when the script that created it is not managed (see ecs_script_parse()), or when the statement that created the entity cannot be attributed to the entity (see ecs_script_entity_source()).
| world | The world. |
| entity | The entity to find. |
| FLECS_API bool ecs_script_entity_source | ( | const ecs_script_t * | script, |
| ecs_entity_t | entity, | ||
| ecs_script_source_t * | source ) |
Find the statement that declares an entity.
This operation returns the source location of the entity statement that declared an entity. The script must have been evaluated at least once, as the mapping from entity to statement is established during evaluation.
Entities that were created by instantiating a template declared by this script are resolved to the statement in the template body that created them. Because a template body statement is shared by all instances of the template, the same statement is returned for every instance, and ecs_script_source_t::template_ is set to the template entity. The template must be declared by this script; when a script instantiates a template that is declared by another script (for example a template from an included file), the body entities are reported by the script that declares the template, not by the script that instantiates it.
The operation returns false when the entity was not created by an entity statement of this script. This is the case for:
An entity that carries the (EcsScriptTemplate, *) pair is never reported as a plain (non-template) statement, also not by the script that instantiates the template.
When an entity is declared by more than one statement, the location of the first declaration is returned.
The returned offsets stay valid until the script is freed or reparsed.
| script | The script. |
| entity | The entity to find. |
| source | Out parameter with the source location (optional). |
| FLECS_API int ecs_script_eval | ( | const ecs_script_t * | script, |
| const ecs_script_eval_desc_t * | desc, | ||
| ecs_script_eval_result_t * | result ) |
Evaluate script.
This operation evaluates (runs) a parsed script.
When the result parameter is not NULL, the script will capture errors and return them in the output struct. If result.error is set, it must be freed by the application.
| script | The script. |
| desc | Parameters for script runtime. |
| result | Output of script evaluation (optional). |
| 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 char * ecs_script_ir_to_str | ( | const ecs_script_t * | script | ) |
Convert script IR to string.
Compiles the script to IR if it hasn't been compiled yet, and returns a human readable listing of the instructions.
| script | The script. |
| FLECS_API ecs_script_t * ecs_script_parse | ( | ecs_world_t * | world, |
| const char * | name, | ||
| const char * | code, | ||
| const ecs_script_eval_desc_t * | desc, | ||
| ecs_script_eval_result_t * | result ) |
Parse script.
This operation parses a script and returns a script object upon success. To run the script, call ecs_script_eval().
When the result parameter is not NULL, the script will capture errors and return them in the output struct. If result.error is set, it must be freed by the application.
| world | The world. |
| name | Name of the script (typically a file or module name). |
| code | The script code. |
| desc | Parameters for script runtime. |
| result | Output of script evaluation. |
| FLECS_API int ecs_script_run | ( | ecs_world_t * | world, |
| const char * | name, | ||
| const char * | code, | ||
| ecs_script_eval_result_t * | result ) |
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. |
| result | Output of script evaluation (optional). |
| 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 int ecs_script_run_file_w_desc | ( | ecs_world_t * | world, |
| const char * | filename, | ||
| const ecs_script_eval_desc_t * | desc ) |
Parse script file and evaluate with options.
Same as ecs_script_run_file(), but accepts a descriptor that configures parsing and evaluation.
| world | The world. |
| filename | The script file name. |
| desc | Parse and evaluation options (optional). |
| FLECS_API int ecs_script_run_w_desc | ( | ecs_world_t * | world, |
| const char * | name, | ||
| const char * | code, | ||
| const ecs_script_eval_desc_t * | desc, | ||
| ecs_script_eval_result_t * | result ) |
Parse script and evaluate with options.
Same as ecs_script_run(), but accepts a descriptor that configures parsing and evaluation, such as skip_unknown or the runtime (AST or IR) to use.
| world | The world. |
| name | The script name (typically the file). |
| code | The script. |
| desc | Parse and evaluation options (optional). |
| result | Output of script evaluation (optional). |
| FLECS_API void ecs_script_runtime_free | ( | ecs_script_runtime_t * | runtime | ) |
Free script runtime.
This operation frees a script runtime created by ecs_script_runtime_new().
| runtime | The runtime to free. |
| FLECS_API ecs_script_runtime_t * ecs_script_runtime_new | ( | void | ) |
Create runtime for script.
A script runtime is a container for any data created during script evaluation. By default, calling ecs_script_run() or ecs_script_eval() will create a runtime on the spot. A runtime can be created in advance and reused across multiple script evaluations to improve performance.
When scripts are evaluated on multiple threads, each thread should have its own script runtime.
A script runtime must be deleted with ecs_script_runtime_free().
| 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 | A 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_var_t * ecs_script_vars_from_sp | ( | const ecs_script_vars_t * | vars, |
| int32_t | sp ) |
Lookup a variable by stack pointer.
This operation provides a faster way to lookup variables that are always declared in the same order in a ecs_script_vars_t scope.
The stack pointer of a variable can be obtained from the ecs_script_var_t type. The provided frame offset must be valid for the provided variable
stack. If the frame offset is not valid, this operation will panic.
| vars | The variable scope. |
| sp | The stack pointer to the variable. |
| 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 void ecs_script_vars_print | ( | const ecs_script_vars_t * | vars | ) |
Print variables.
This operation prints all variables in the vars scope and parent scopes.
| vars | The variable scope. |
| 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 ecs_script_vars_set_size | ( | ecs_script_vars_t * | vars, |
| int32_t | count ) |
Preallocate space for variables.
This operation preallocates space for the specified number of variables. This is a performance optimization only, and is not necessary before declaring variables in a scope.
| vars | The variable scope. |
| count | The number of variables to preallocate space for. |
| FLECS_API void FlecsScriptImport | ( | ecs_world_t * | world | ) |