Flecs: include/flecs/addons/script.h Source File
Description: A fast entity component system (ECS) for C & C++

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

Loading...
Searching...
No Matches
script.h
Go to the documentation of this file.
1
7
8#ifdef FLECS_SCRIPT
9
17
18#ifndef FLECS_META
19#define FLECS_META
20#endif
21
22#ifndef FLECS_DOC
23#define FLECS_DOC
24#endif
25
26#ifndef FLECS_PARSER
27#define FLECS_PARSER
28#endif
29
30#ifndef FLECS_SCRIPT_H
31#define FLECS_SCRIPT_H
32
33#ifdef __cplusplus
34extern "C" {
35#endif
36
37#define FLECS_SCRIPT_FUNCTION_ARGS_MAX (16)
38
39FLECS_API
40extern ECS_COMPONENT_DECLARE(EcsScript);
41
42FLECS_API
43extern ECS_DECLARE(EcsScriptTemplate);
44
45FLECS_API
46extern ECS_COMPONENT_DECLARE(EcsScriptConstVar);
47
48FLECS_API
49extern ECS_COMPONENT_DECLARE(EcsScriptFunction);
50
51FLECS_API
52extern ECS_COMPONENT_DECLARE(EcsScriptMethod);
53
54/* Script template. */
55typedef struct ecs_script_template_t ecs_script_template_t;
56
58 typedef struct ecs_script_var_t {
59 const char *name;
60 ecs_value_t value;
61 const ecs_type_info_t *type_info;
62 int32_t sp;
63 bool is_const;
64} ecs_script_var_t;
65
67 typedef struct ecs_script_vars_t {
68 struct ecs_script_vars_t *parent;
69 int32_t sp;
70
71 ecs_hashmap_t var_index;
72 ecs_vec_t vars;
73
74 const ecs_world_t *world;
75 struct ecs_stack_t *stack;
76 ecs_stack_cursor_t *cursor;
77 ecs_allocator_t *allocator;
78} ecs_script_vars_t;
79
81 typedef struct ecs_script_t {
82 ecs_world_t *world;
83 const char *name;
84 const char *code;
85} ecs_script_t;
86
87/* Runtime for executing scripts */
88typedef struct ecs_script_runtime_t ecs_script_runtime_t;
89
93 typedef struct EcsScript {
94 char *filename;
95 char *code;
96 char *error; /* Set if script evaluation had errors */
97 ecs_script_t *script;
98 ecs_script_template_t *template_; /* Only set for template scripts */
99} EcsScript;
100
102 typedef struct ecs_function_ctx_t {
103 ecs_world_t *world;
104 ecs_entity_t function;
105 void *ctx;
106} ecs_function_ctx_t;
107
109 typedef void(*ecs_function_callback_t)(
110 const ecs_function_ctx_t *ctx,
111 int32_t argc,
112 const ecs_value_t *argv,
113 ecs_value_t *result);
114
116 typedef struct ecs_script_parameter_t {
117 const char *name;
118 ecs_entity_t type;
119} ecs_script_parameter_t;
120
124 typedef struct EcsScriptConstVar {
125 ecs_value_t value;
126 const ecs_type_info_t *type_info;
127} EcsScriptConstVar;
128
132 typedef struct EcsScriptFunction {
133 ecs_entity_t return_type;
134 ecs_vec_t params; /* vec<ecs_script_parameter_t> */
135 ecs_function_callback_t callback;
136 void *ctx;
137} EcsScriptFunction;
138
144 typedef struct EcsScriptMethod {
145 ecs_entity_t return_type;
146 ecs_vec_t params; /* vec<ecs_script_parameter_t> */
147 ecs_function_callback_t callback;
148 void *ctx;
149} EcsScriptMethod;
150
151/* Parsing & running scripts */
152
154 typedef struct ecs_script_eval_desc_t {
155 ecs_script_vars_t *vars;
156 ecs_script_runtime_t *runtime;
157} ecs_script_eval_desc_t;
158
160 typedef struct ecs_script_eval_result_t {
161 char *error;
162} ecs_script_eval_result_t;
163
183FLECS_API
184 ecs_script_t* ecs_script_parse(
185 ecs_world_t *world,
186 const char *name,
187 const char *code,
188 const ecs_script_eval_desc_t *desc,
189 ecs_script_eval_result_t *result);
190
206FLECS_API
207 int ecs_script_eval(
208 const ecs_script_t *script,
209 const ecs_script_eval_desc_t *desc,
210 ecs_script_eval_result_t *result);
211
221FLECS_API
222 void ecs_script_free(
223 ecs_script_t *script);
224
240FLECS_API
241 int ecs_script_run(
242 ecs_world_t *world,
243 const char *name,
244 const char *code,
245 ecs_script_eval_result_t *result);
246
256FLECS_API
257 int ecs_script_run_file(
258 ecs_world_t *world,
259 const char *filename);
260
274FLECS_API
275ecs_script_runtime_t* ecs_script_runtime_new(void);
276
282FLECS_API
283 void ecs_script_runtime_free(
284 ecs_script_runtime_t *runtime);
285
294FLECS_API
295 int ecs_script_ast_to_buf(
296 ecs_script_t *script,
297 ecs_strbuf_t *buf,
298 bool colors);
299
307FLECS_API
308 char* ecs_script_ast_to_str(
309 ecs_script_t *script,
310 bool colors);
311
312
313/* Managed scripts (script associated with entity that outlives the function) */
314
316 typedef struct ecs_script_desc_t {
317 ecs_entity_t entity; /* Set to customize entity handle associated with script */
318 const char *filename; /* Set to load script from file */
319 const char *code; /* Set to parse script from string */
320} ecs_script_desc_t;
321
332FLECS_API
333 ecs_entity_t ecs_script_init(
334 ecs_world_t *world,
335 const ecs_script_desc_t *desc);
336
337#define ecs_script(world, ...)\
338 ecs_script_init(world, &(ecs_script_desc_t) __VA_ARGS__)
339
347FLECS_API
348 int ecs_script_update(
349 ecs_world_t *world,
350 ecs_entity_t script,
351 ecs_entity_t instance,
352 const char *code);
353
360FLECS_API
361 void ecs_script_clear(
362 ecs_world_t *world,
363 ecs_entity_t script,
364 ecs_entity_t instance);
365
366
367/* Script variables */
368
385FLECS_API
386 ecs_script_vars_t* ecs_script_vars_init(
387 ecs_world_t *world);
388
395FLECS_API
396 void ecs_script_vars_fini(
397 ecs_script_vars_t *vars);
398
410FLECS_API
411 ecs_script_vars_t* ecs_script_vars_push(
412 ecs_script_vars_t *parent);
413
422FLECS_API
423 ecs_script_vars_t* ecs_script_vars_pop(
424 ecs_script_vars_t *vars);
425
438FLECS_API
439 ecs_script_var_t* ecs_script_vars_declare(
440 ecs_script_vars_t *vars,
441 const char *name);
442
458FLECS_API
459 ecs_script_var_t* ecs_script_vars_define_id(
460 ecs_script_vars_t *vars,
461 const char *name,
462 ecs_entity_t type);
463
464#define ecs_script_vars_define(vars, name, type)\
465 ecs_script_vars_define_id(vars, name, ecs_id(type))
466
476FLECS_API
477 ecs_script_var_t* ecs_script_vars_lookup(
478 const ecs_script_vars_t *vars,
479 const char *name);
480
493FLECS_API
494 ecs_script_var_t* ecs_script_vars_from_sp(
495 const ecs_script_vars_t *vars,
496 int32_t sp);
497
503FLECS_API
504 void ecs_script_vars_print(
505 const ecs_script_vars_t *vars);
506
515FLECS_API
516 void ecs_script_vars_set_size(
517 ecs_script_vars_t *vars,
518 int32_t count);
519
552FLECS_API
553 void ecs_script_vars_from_iter(
554 const ecs_iter_t *it,
555 ecs_script_vars_t *vars,
556 int offset);
557
558
559/* Standalone expression evaluation */
560
562 typedef struct ecs_expr_eval_desc_t {
563 const char *name;
564 const char *expr;
565 const ecs_script_vars_t *vars;
566 ecs_entity_t type;
567 ecs_entity_t (*lookup_action)(
568 const ecs_world_t*,
569 const char *value,
570 void *ctx);
571 void *lookup_ctx;
572
574 bool disable_folding;
575
579 bool disable_dynamic_variable_binding;
580
583 bool allow_unresolved_identifiers;
584
585 ecs_script_runtime_t *runtime;
586
587 void *script_visitor;
588} ecs_expr_eval_desc_t;
589
604FLECS_API
605 const char* ecs_expr_run(
606 ecs_world_t *world,
607 const char *ptr,
608 ecs_value_t *value,
609 const ecs_expr_eval_desc_t *desc);
610
620FLECS_API
621 ecs_script_t* ecs_expr_parse(
622 ecs_world_t *world,
623 const char *expr,
624 const ecs_expr_eval_desc_t *desc);
625
640FLECS_API
641 int ecs_expr_eval(
642 const ecs_script_t *script,
643 ecs_value_t *value,
644 const ecs_expr_eval_desc_t *desc);
645
658FLECS_API
659 char* ecs_script_string_interpolate(
660 ecs_world_t *world,
661 const char *str,
662 const ecs_script_vars_t *vars);
663
664
665/* Global const variables */
666
668 typedef struct ecs_const_var_desc_t {
669 /* Variable name. */
670 const char *name;
671
672 /* Variable parent (namespace). */
673 ecs_entity_t parent;
674
675 /* Variable type. */
676 ecs_entity_t type;
677
678 /* Pointer to value of variable. The value will be copied to an internal
679 * storage and does not need to be kept alive. */
680 void *value;
681} ecs_const_var_desc_t;
682
689FLECS_API
690 ecs_entity_t ecs_const_var_init(
691 ecs_world_t *world,
692 ecs_const_var_desc_t *desc);
693
694#define ecs_const_var(world, ...)\
695 ecs_const_var_init(world, &(ecs_const_var_desc_t)__VA_ARGS__)
696
697
705FLECS_API
706 ecs_value_t ecs_const_var_get(
707 const ecs_world_t *world,
708 ecs_entity_t var);
709
710/* Functions */
711
713 typedef struct ecs_function_desc_t {
715 const char *name;
716
719 ecs_entity_t parent;
720
722 ecs_script_parameter_t params[FLECS_SCRIPT_FUNCTION_ARGS_MAX];
723
725 ecs_entity_t return_type;
726
728 ecs_function_callback_t callback;
729
731 void *ctx;
732} ecs_function_desc_t;
733
741FLECS_API
742 ecs_entity_t ecs_function_init(
743 ecs_world_t *world,
744 const ecs_function_desc_t *desc);
745
746#define ecs_function(world, ...)\
747 ecs_function_init(world, &(ecs_function_desc_t)__VA_ARGS__)
748
761FLECS_API
762 ecs_entity_t ecs_method_init(
763 ecs_world_t *world,
764 const ecs_function_desc_t *desc);
765
766#define ecs_method(world, ...)\
767 ecs_method_init(world, &(ecs_function_desc_t)__VA_ARGS__)
768
769
770/* Value serialization */
771
781FLECS_API
782 char* ecs_ptr_to_expr(
783 const ecs_world_t *world,
784 ecs_entity_t type,
785 const void *data);
786
796FLECS_API
797 int ecs_ptr_to_expr_buf(
798 const ecs_world_t *world,
799 ecs_entity_t type,
800 const void *data,
801 ecs_strbuf_t *buf);
802
814FLECS_API
815 char* ecs_ptr_to_str(
816 const ecs_world_t *world,
817 ecs_entity_t type,
818 const void *data);
819
829FLECS_API
830 int ecs_ptr_to_str_buf(
831 const ecs_world_t *world,
832 ecs_entity_t type,
833 const void *data,
834 ecs_strbuf_t *buf);
835
836typedef struct ecs_expr_node_t ecs_expr_node_t;
837
846FLECS_API
847 void FlecsScriptImport(
848 ecs_world_t *world);
849
850#ifdef __cplusplus
851}
852#endif
853
854#endif
855
857
858#endif
ecs_script_runtime_free
FLECS_API void ecs_script_runtime_free(ecs_script_runtime_t *runtime)
Free script runtime.
ecs_script_eval
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.
ecs_script_vars_print
FLECS_API void ecs_script_vars_print(const ecs_script_vars_t *vars)
Print variables.
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.
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.
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.
ecs_script_vars_fini
FLECS_API void ecs_script_vars_fini(ecs_script_vars_t *vars)
Free variable scope.
ecs_script_runtime_new
FLECS_API ecs_script_runtime_t * ecs_script_runtime_new(void)
Create runtime for script.
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.
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_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.
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.
ecs_script_ast_to_str
FLECS_API char * ecs_script_ast_to_str(ecs_script_t *script, bool colors)
Convert script AST to string.
ecs_function_callback_t
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 script.h:109
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_vars_pop
FLECS_API ecs_script_vars_t * ecs_script_vars_pop(ecs_script_vars_t *vars)
Pop variable scope.
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.
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.
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.
ecs_const_var_get
FLECS_API ecs_value_t ecs_const_var_get(const ecs_world_t *world, ecs_entity_t var)
Returns value for a const variable.
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.
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.
ecs_script_free
FLECS_API void ecs_script_free(ecs_script_t *script)
Free script.
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.
ecs_method_init
FLECS_API ecs_entity_t ecs_method_init(ecs_world_t *world, const ecs_function_desc_t *desc)
Create new method.
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.
ecs_script_run
FLECS_API int ecs_script_run(ecs_world_t *world, const char *name, const char *code, ecs_script_eval_result_t *result)
Parse script.
ecs_script_vars_init
FLECS_API ecs_script_vars_t * ecs_script_vars_init(ecs_world_t *world)
Create new variable scope.
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.
ecs_script_vars_push
FLECS_API ecs_script_vars_t * ecs_script_vars_push(ecs_script_vars_t *parent)
Push new variable scope.
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, ecs_script_eval_result_t *result)
Parse script.
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.
FlecsScriptImport
FLECS_API void FlecsScriptImport(ecs_world_t *world)
Script module import function.
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.
ecs_script_run_file
FLECS_API int ecs_script_run_file(ecs_world_t *world, const char *filename)
Parse script file.
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.
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.
ecs_entity_t
ecs_id_t ecs_entity_t
An entity identifier.
Definition flecs.h:361
ecs_world_t
struct ecs_world_t ecs_world_t
A world is the container for all ECS data and supporting features.
Definition flecs.h:405
script
script_builder script(const char *name=nullptr) const
Build script.
Definition mixin.inl:31
ECS_COMPONENT_DECLARE
#define ECS_COMPONENT_DECLARE(id)
Forward declare a component.
Definition flecs_c.h:112
EcsScriptConstVar
Const component.
Definition script.h:124
EcsScriptFunction
Function component.
Definition script.h:132
EcsScriptMethod
Method component.
Definition script.h:144
EcsScript
Script component.
Definition script.h:93
ecs_const_var_desc_t
Used with ecs_const_var_init.
Definition script.h:668
ecs_expr_eval_desc_t
Used with ecs_expr_run().
Definition script.h:562
ecs_expr_eval_desc_t::disable_folding
bool disable_folding
Disable constant folding (slower evaluation, faster parsing).
Definition script.h:574
ecs_expr_eval_desc_t::script_visitor
void * script_visitor
For internal usage.
Definition script.h:587
ecs_expr_eval_desc_t::type
ecs_entity_t type
Type of parsed value (optional).
Definition script.h:566
ecs_expr_eval_desc_t::vars
const ecs_script_vars_t * vars
Variables accessible in expression.
Definition script.h:565
ecs_expr_eval_desc_t::runtime
ecs_script_runtime_t * runtime
Reusable runtime (optional).
Definition script.h:585
ecs_expr_eval_desc_t::allow_unresolved_identifiers
bool allow_unresolved_identifiers
Allow for unresolved identifiers when parsing.
Definition script.h:583
ecs_expr_eval_desc_t::name
const char * name
Script name.
Definition script.h:563
ecs_expr_eval_desc_t::expr
const char * expr
Full expression string.
Definition script.h:564
ecs_expr_eval_desc_t::disable_dynamic_variable_binding
bool disable_dynamic_variable_binding
This option instructs the expression runtime to lookup variables by stack pointer instead of by name,...
Definition script.h:579
ecs_expr_eval_desc_t::lookup_ctx
void * lookup_ctx
Context passed to lookup function.
Definition script.h:571
ecs_function_ctx_t
Script function context.
Definition script.h:102
ecs_function_desc_t
Used with ecs_function_init and ecs_method_init.
Definition script.h:713
ecs_function_desc_t::return_type
ecs_entity_t return_type
Function return type.
Definition script.h:725
ecs_function_desc_t::name
const char * name
Function name.
Definition script.h:715
ecs_function_desc_t::params
ecs_script_parameter_t params[(16)]
Function parameters.
Definition script.h:722
ecs_function_desc_t::ctx
void * ctx
Context passed to function implementation.
Definition script.h:731
ecs_function_desc_t::callback
ecs_function_callback_t callback
Function implementation.
Definition script.h:728
ecs_function_desc_t::parent
ecs_entity_t parent
Parent of function.
Definition script.h:719
ecs_iter_t
Iterator.
Definition flecs.h:1142
ecs_script_desc_t
Used with ecs_script_init().
Definition script.h:316
ecs_script_eval_desc_t
Used with ecs_script_parse() and ecs_script_eval().
Definition script.h:154
ecs_script_eval_desc_t::runtime
ecs_script_runtime_t * runtime
Reusable runtime (optional).
Definition script.h:156
ecs_script_eval_desc_t::vars
ecs_script_vars_t * vars
Variables used by script.
Definition script.h:155
ecs_script_eval_result_t
Used to capture error output from script evaluation.
Definition script.h:160
ecs_script_parameter_t
Function argument type.
Definition script.h:116
ecs_script_t
Script object.
Definition script.h:81
ecs_script_var_t
Script variable.
Definition script.h:58
ecs_script_vars_t
Script variable scope.
Definition script.h:67
ecs_type_info_t
Type that contains component information (passed to ctors/dtors/...).
Definition flecs.h:995
ecs_value_t
Utility to hold a value of a dynamic type.
Definition flecs.h:1009