Flecs: Flecs script
Description: A fast entity component system (ECS) for C & C++

| Flecs v4.0 A fast entity component system (ECS) for C & C++

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
Flecs script
C API » Addons

DSL for loading scenes, assets and configuration. More...

Collaboration diagram for Flecs script:

## 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_function_ctx_t
| Script function context. More...
struct | ecs_script_parameter_t
| Function argument type. More...
struct | EcsScriptConstVar
| Const component. More...
struct | EcsScriptFunction
| Function component. More...
struct | EcsScriptMethod
| Method component. More...
struct | ecs_script_eval_desc_t
| Used with ecs_script_parse() and ecs_script_eval() More...
struct | ecs_script_desc_t
| Used with ecs_script_init() More...
struct | ecs_expr_eval_desc_t
| Used with ecs_expr_run(). More...
struct | ecs_const_var_desc_t
| Used with ecs_const_var_init. More...
struct | ecs_function_desc_t
| Used with ecs_function_init and ecs_method_init. More...

## Macros
#define | FLECS_PARSER
#define | FLECS_SCRIPT_H
#define | FLECS_SCRIPT_FUNCTION_ARGS_MAX (16)
#define | ecs_script(world, ...)
#define | ecs_script_vars_define(vars, name, type)
#define | ecs_const_var(world, ...)
#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
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 struct ecs_script_parameter_t | ecs_script_parameter_t
| Function argument type.
typedef struct EcsScriptConstVar | EcsScriptConstVar
| Const component.
typedef struct EcsScriptFunction | EcsScriptFunction
| Function component.
typedef struct EcsScriptMethod | EcsScriptMethod
| Method component.
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_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_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_COMPONENT_DECLARE (EcsScriptConstVar)
FLECS_API | ECS_COMPONENT_DECLARE (EcsScriptFunction)
FLECS_API | ECS_COMPONENT_DECLARE (EcsScriptMethod)
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)
| Parse script.
FLECS_API int | ecs_script_eval (const ecs_script_t *script, const ecs_script_eval_desc_t *desc)
| 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 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 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 This operation converts an iterator to a variable array.
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_entity_t | ecs_function_init (ecs_world_t *world, const ecs_function_desc_t *desc)
| Create new function.
FLECS_API ecs_entity_t | ecs_method_init (ecs_world_t *world, const ecs_function_desc_t *desc)
| Create new method.
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.

## Detailed Description

DSL for loading scenes, assets and configuration.

## Macro Definition Documentation

## ◆ ecs_const_var

#define ecs_const_var | ( |  | world,
|  |  | ... )

Value:
ecs_const_var_init(world, &(ecs_const_var_desc_t)__VA_ARGS__)
ecs_const_var_init
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.
ecs_const_var_desc_t
Used with ecs_const_var_init.
Definition script.h:646

Definition at line 672 of file script.h.

## ◆ ecs_function

#define ecs_function | ( |  | world,
|  |  | ... )

Value:
ecs_function_init(world, &(ecs_function_desc_t)__VA_ARGS__)
ecs_function_init
FLECS_API ecs_entity_t ecs_function_init(ecs_world_t *world, const ecs_function_desc_t *desc)
Create new function.
ecs_function_desc_t
Used with ecs_function_init and ecs_method_init.
Definition script.h:678

Definition at line 711 of file script.h.

## ◆ ecs_method

#define ecs_method | ( |  | world,
|  |  | ... )

Value:
ecs_method_init(world, &(ecs_function_desc_t)__VA_ARGS__)
ecs_method_init
FLECS_API ecs_entity_t ecs_method_init(ecs_world_t *world, const ecs_function_desc_t *desc)
Create new method.

Definition at line 731 of file script.h.

## ◆ ecs_script

#define ecs_script | ( |  | world,
|  |  | ... )

Value:
ecs_script_init(world, &(ecs_script_desc_t) __VA_ARGS__)
ecs_script_init
FLECS_API ecs_entity_t ecs_script_init(ecs_world_t *world, const ecs_script_desc_t *desc)
Load managed script.
ecs_script_desc_t
Used with ecs_script_init()
Definition script.h:296

Definition at line 317 of file script.h.

## ◆ ecs_script_vars_define

#define ecs_script_vars_define | ( |  | vars,
|  |  | name,
|  |  | type )

Value:
ecs_script_vars_define_id(vars, name, ecs_id(type))
ecs_id
FLECS_API const ecs_entity_t ecs_id(EcsDocDescription)
Component id for EcsDocDescription.
ecs_script_vars_define_id
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.

Definition at line 444 of file script.h.

## ◆ FLECS_PARSER

#define FLECS_PARSER

Definition at line 27 of file script.h.

## ◆ FLECS_SCRIPT_FUNCTION_ARGS_MAX

#define FLECS_SCRIPT_FUNCTION_ARGS_MAX (16)

Definition at line 37 of file script.h.

## ◆ FLECS_SCRIPT_H

#define FLECS_SCRIPT_H

Definition at line 31 of file script.h.

## Typedef Documentation

## ◆ ecs_expr_node_t

typedef struct ecs_expr_node_t ecs_expr_node_t

Definition at line 801 of file script.h.

## ◆ ecs_function_callback_t

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.

Definition at line 106 of file script.h.

## ◆ ecs_script_runtime_t

typedef struct ecs_script_runtime_t ecs_script_runtime_t

Definition at line 88 of file script.h.

## ◆ ecs_script_template_t

typedef struct ecs_script_template_t ecs_script_template_t

Definition at line 55 of file script.h.

## ◆ EcsScript

typedef struct EcsScript EcsScript

Script component.

This component is added to the entities of managed scripts and templates.

## ◆ EcsScriptConstVar

typedef struct EcsScriptConstVar EcsScriptConstVar

Const component.

This component describes a const variable that can be used from scripts.

## ◆ EcsScriptFunction

typedef struct EcsScriptFunction EcsScriptFunction

Function component.

This component describes a function that can be called from a script.

## ◆ EcsScriptMethod

typedef struct EcsScriptMethod EcsScriptMethod

Method component.

This component describes a method that can be called from a script. Methods are functions that can be called on instances of a type. A method entity is stored in the scope of the type it belongs to.

## Function Documentation

## ◆ ecs_const_var_init()

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.

Parameters

  world | The world.
  desc | Const var parameters.

Returns
  The const var, or 0 if failed.

## ◆ ecs_expr_eval()

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_value_free() afterwards.

Parameters

  script | The script containing the expression.
  value | The value in which to store the expression result.
  desc | Configuration parameters for the parser.

Returns
  Zero if successful, non-zero if failed.

## ◆ ecs_expr_parse()

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().

Parameters

  world | The world.
  expr | The expression string.
  desc | Configuration parameters for the parser.

Returns
  A script object if parsing is successful, NULL if parsing failed.

## ◆ ecs_expr_run()

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_value_free() afterwards.

Parameters

  world | The world.
  ptr | The pointer to the expression to parse.
  value | The value containing type & pointer to write to.
  desc | Configuration parameters for the parser.

Returns
  Pointer to the character after the last one read, or NULL if failed.

## ◆ ecs_function_init()

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.

Parameters

  world | The world.
  desc | Function init parameters.

Returns
  The function, or 0 if failed.

## ◆ ecs_method_init()

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.

Parameters

  world | Method The world.
  desc | Method init parameters.

Returns
  The function, or 0 if failed.

## ◆ ecs_ptr_to_expr()

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.

Parameters

  world | The world.
  type | The type of the value to serialize.
  data | The value to serialize.

Returns
  String with expression, or NULL if failed.

## ◆ ecs_ptr_to_expr_buf()

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.

Parameters

  world | The world.
  type | The type of the value to serialize.
  data | The value to serialize.
  buf | The strbuf to append the string to.

Returns
  Zero if success, non-zero if failed.

## ◆ ecs_ptr_to_str()

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:

- Strings are not quoted

Parameters

  world | The world.
  type | The type of the value to serialize.
  data | The value to serialize.

Returns
  String with result, or NULL if failed.

## ◆ ecs_ptr_to_str_buf()

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.

Parameters

  world | The world.
  type | The type of the value to serialize.
  data | The value to serialize.
  buf | The strbuf to append the string to.

Returns
  Zero if success, non-zero if failed.

## ◆ ecs_script_ast_to_buf()

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.

Parameters

  script | The script.
  buf | The buffer to write to.

Returns
  Zero if success, non-zero if failed.

## ◆ ecs_script_ast_to_str()

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.

Parameters

  script | The script.

Returns
  The string if success, NULL if failed.

## ◆ ecs_script_clear()

FLECS_API void ecs_script_clear | ( | ecs_world_t * | world,
|  | ecs_entity_t | script,
|  | ecs_entity_t | instance )

Clear all entities associated with script.

Parameters

  world | The world.
  script | The script entity.
  instance | The script instance.

## ◆ ecs_script_eval()

FLECS_API int ecs_script_eval | ( | const ecs_script_t * | script,
|  | const ecs_script_eval_desc_t * | desc )

Evaluate script.

This operation evaluates (runs) a parsed script.

If variables were provided to ecs_script_parse(), an application may pass a different ecs_script_vars_t object to ecs_script_eval(), as long as the object has all referenced variables and they are of the same type.

Parameters

  script | The script.
  desc | Parameters for script runtime.

Returns
  Zero if success, non-zero if failed.

## ◆ ecs_script_free()

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.

Parameters

  script | The script.

## ◆ ecs_script_init()

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.

Parameters

  world | The world.
  desc | Script descriptor.

## ◆ ecs_script_parse()

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 )

Parse script.

This operation parses a script and returns a script object upon success. To run the script, call ecs_script_eval().

If the script uses outside variables, an ecs_script_vars_t object must be provided in the vars member of the desc object that defines all variables with the correct types.

Parameters

  world | The world.
  name | Name of the script (typically a file/module name).
  code | The script code.
  desc | Parameters for script runtime.

Returns
  Script object if success, NULL if failed.

## ◆ ecs_script_run()

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:

ecs_script_t *script = ecs_script_parse(world, name, code);
ecs_script_eval(script);
ecs_script_free(script);
ecs_script_parse
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)
Parse script.
ecs_script_free
FLECS_API void ecs_script_free(ecs_script_t *script)
Free script.
ecs_script_eval
FLECS_API int ecs_script_eval(const ecs_script_t *script, const ecs_script_eval_desc_t *desc)
Evaluate script.
script
script_builder script(const char *name=nullptr) const
Build script.
Definition mixin.inl:31
ecs_script_t
Script object.
Definition script.h:81

Parameters

  world | The world.
  name | The script name (typically the file).
  code | The script.

Returns
  Zero if success, non-zero otherwise.

## ◆ ecs_script_run_file()

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().

Parameters

  world | The world.
  filename | The script file name.

Returns
  Zero if success, non-zero if failed.

## ◆ ecs_script_runtime_free()

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().

Parameters

  runtime | The runtime to free.

## ◆ ecs_script_runtime_new()

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().

Returns
  A new script runtime.

## ◆ ecs_script_string_interpolate()

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:

- $variable_name
- {expression}

The $, { and } characters can be escaped with a backslash ().

Parameters

  world | The world.
  str | The string to evaluate.
  vars | The variables to use for evaluation.

## ◆ ecs_script_update()

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.

Parameters

  world | The world.
  script | The script entity.
  instance | An template instance (optional).
  code | The script code.

## ◆ ecs_script_vars_declare()

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.

Parameters

  vars | The variable scope.
  name | The variable name.

Returns
  The new variable, or NULL if the operation failed.

## ◆ ecs_script_vars_define_id()

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.

Parameters

  vars | The variable scope.
  name | The variable name.
  type | The variable type.

Returns
  The new variable, or NULL if the operation failed.

## ◆ ecs_script_vars_fini()

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.

Parameters

  vars | The variable scope.

## ◆ ecs_script_vars_from_iter()

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.

Parameters

  it | The iterator to convert to variables.
  vars | The variables to write to.
  offset | The offset to the current element.

## ◆ ecs_script_vars_from_sp()

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.

Parameters

  vars | The variable scope.
  sp | The stack pointer to the variable.

Returns
  The variable.

## ◆ ecs_script_vars_init()

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.

Parameters

  world | The world.

## ◆ ecs_script_vars_lookup()

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.

Parameters

  vars | The variable scope.
  name | The variable name.

Returns
  The variable, or NULL if one with the provided name does not exist.

## ◆ ecs_script_vars_pop()

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.

Parameters

  vars | The scope to free.

Returns
  The parent scope.

## ◆ ecs_script_vars_print()

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.asm

Parameters

  vars | The variable scope.

## ◆ ecs_script_vars_push()

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.

Parameters

  parent | The parent scope (provide NULL for root scope).

Returns
  The new variable scope.

## ◆ ecs_script_vars_set_size()

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.

Parameters

  vars | The variable scope.
  count | The number of variables to preallocate space for.

## ◆ FlecsScriptImport()

FLECS_API void FlecsScriptImport | ( | ecs_world_t * | world | ) |

Script module import function.

Usage:

ECS_IMPORT(world, FlecsScript)
ECS_IMPORT
#define ECS_IMPORT(world, id)
Wrapper around ecs_import().
Definition module.h:119

Parameters

  world | The world.