Flecs: include/flecs/addons/script.h Source File
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
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 ecs_script_t *script;
95 ecs_script_template_t *template_; /* Only set for template scripts */
96} EcsScript;
97
99 typedef struct ecs_function_ctx_t {
100 ecs_world_t *world;
101 ecs_entity_t function;
102 void *ctx;
103} ecs_function_ctx_t;
104
106 typedef void(*ecs_function_callback_t)(
107 const ecs_function_ctx_t *ctx,
108 int32_t argc,
109 const ecs_value_t *argv,
110 ecs_value_t *result);
111
113 typedef struct ecs_script_parameter_t {
114 const char *name;
115 ecs_entity_t type;
116} ecs_script_parameter_t;
117
121 typedef struct EcsScriptConstVar {
122 ecs_value_t value;
123 const ecs_type_info_t *type_info;
124} EcsScriptConstVar;
125
129 typedef struct EcsScriptFunction {
130 ecs_entity_t return_type;
131 ecs_vec_t params; /* vec<ecs_script_parameter_t> */
132 ecs_function_callback_t callback;
133 void *ctx;
134} EcsScriptFunction;
135
141 typedef struct EcsScriptMethod {
142 ecs_entity_t return_type;
143 ecs_vec_t params; /* vec<ecs_script_parameter_t> */
144 ecs_function_callback_t callback;
145 void *ctx;
146} EcsScriptMethod;
147
148/* Parsing & running scripts */
149
151 typedef struct ecs_script_eval_desc_t {
152 ecs_script_vars_t *vars;
153 ecs_script_runtime_t *runtime;
154} ecs_script_eval_desc_t;
155
170FLECS_API
171 ecs_script_t* ecs_script_parse(
172 ecs_world_t *world,
173 const char *name,
174 const char *code,
175 const ecs_script_eval_desc_t *desc);
176
188FLECS_API
189 int ecs_script_eval(
190 const ecs_script_t *script,
191 const ecs_script_eval_desc_t *desc);
192
202FLECS_API
203 void ecs_script_free(
204 ecs_script_t *script);
205
221FLECS_API
222 int ecs_script_run(
223 ecs_world_t *world,
224 const char *name,
225 const char *code);
226
236FLECS_API
237 int ecs_script_run_file(
238 ecs_world_t *world,
239 const char *filename);
240
254FLECS_API
255ecs_script_runtime_t* ecs_script_runtime_new(void);
256
262FLECS_API
263 void ecs_script_runtime_free(
264 ecs_script_runtime_t *runtime);
265
274FLECS_API
275 int ecs_script_ast_to_buf(
276 ecs_script_t *script,
277 ecs_strbuf_t *buf,
278 bool colors);
279
287FLECS_API
288 char* ecs_script_ast_to_str(
289 ecs_script_t *script,
290 bool colors);
291
292
293/* Managed scripts (script associated with entity that outlives the function) */
294
296 typedef struct ecs_script_desc_t {
297 ecs_entity_t entity; /* Set to customize entity handle associated with script */
298 const char *filename; /* Set to load script from file */
299 const char *code; /* Set to parse script from string */
300} ecs_script_desc_t;
301
312FLECS_API
313 ecs_entity_t ecs_script_init(
314 ecs_world_t *world,
315 const ecs_script_desc_t *desc);
316
317#define ecs_script(world, ...)\
318 ecs_script_init(world, &(ecs_script_desc_t) __VA_ARGS__)
319
327FLECS_API
328 int ecs_script_update(
329 ecs_world_t *world,
330 ecs_entity_t script,
331 ecs_entity_t instance,
332 const char *code);
333
340FLECS_API
341 void ecs_script_clear(
342 ecs_world_t *world,
343 ecs_entity_t script,
344 ecs_entity_t instance);
345
346
347/* Script variables */
348
365FLECS_API
366 ecs_script_vars_t* ecs_script_vars_init(
367 ecs_world_t *world);
368
375FLECS_API
376 void ecs_script_vars_fini(
377 ecs_script_vars_t *vars);
378
390FLECS_API
391 ecs_script_vars_t* ecs_script_vars_push(
392 ecs_script_vars_t *parent);
393
402FLECS_API
403 ecs_script_vars_t* ecs_script_vars_pop(
404 ecs_script_vars_t *vars);
405
418FLECS_API
419 ecs_script_var_t* ecs_script_vars_declare(
420 ecs_script_vars_t *vars,
421 const char *name);
422
438FLECS_API
439 ecs_script_var_t* ecs_script_vars_define_id(
440 ecs_script_vars_t *vars,
441 const char *name,
442 ecs_entity_t type);
443
444#define ecs_script_vars_define(vars, name, type)\
445 ecs_script_vars_define_id(vars, name, ecs_id(type))
446
456FLECS_API
457 ecs_script_var_t* ecs_script_vars_lookup(
458 const ecs_script_vars_t *vars,
459 const char *name);
460
473FLECS_API
474 ecs_script_var_t* ecs_script_vars_from_sp(
475 const ecs_script_vars_t *vars,
476 int32_t sp);
477
483FLECS_API
484 void ecs_script_vars_print(
485 const ecs_script_vars_t *vars);
486
495FLECS_API
496 void ecs_script_vars_set_size(
497 ecs_script_vars_t *vars,
498 int32_t count);
499
532FLECS_API
533 void ecs_script_vars_from_iter(
534 const ecs_iter_t *it,
535 ecs_script_vars_t *vars,
536 int offset);
537
538
539/* Standalone expression evaluation */
540
542 typedef struct ecs_expr_eval_desc_t {
543 const char *name;
544 const char *expr;
545 const ecs_script_vars_t *vars;
546 ecs_entity_t type;
547 ecs_entity_t (*lookup_action)(
548 const ecs_world_t*,
549 const char *value,
550 void *ctx);
551 void *lookup_ctx;
552
554 bool disable_folding;
555
559 bool disable_dynamic_variable_binding;
560
563 bool allow_unresolved_identifiers;
564
565 ecs_script_runtime_t *runtime;
566} ecs_expr_eval_desc_t;
567
582FLECS_API
583 const char* ecs_expr_run(
584 ecs_world_t *world,
585 const char *ptr,
586 ecs_value_t *value,
587 const ecs_expr_eval_desc_t *desc);
588
598FLECS_API
599 ecs_script_t* ecs_expr_parse(
600 ecs_world_t *world,
601 const char *expr,
602 const ecs_expr_eval_desc_t *desc);
603
618FLECS_API
619 int ecs_expr_eval(
620 const ecs_script_t *script,
621 ecs_value_t *value,
622 const ecs_expr_eval_desc_t *desc);
623
636FLECS_API
637 char* ecs_script_string_interpolate(
638 ecs_world_t *world,
639 const char *str,
640 const ecs_script_vars_t *vars);
641
642
643/* Global const variables */
644
646 typedef struct ecs_const_var_desc_t {
647 /* Variable name. */
648 const char *name;
649
650 /* Variable parent (namespace). */
651 ecs_entity_t parent;
652
653 /* Variable type. */
654 ecs_entity_t type;
655
656 /* Pointer to value of variable. The value will be copied to an internal
657 * storage and does not need to be kept alive. */
658 void *value;
659} ecs_const_var_desc_t;
660
667FLECS_API
668 ecs_entity_t ecs_const_var_init(
669 ecs_world_t *world,
670 ecs_const_var_desc_t *desc);
671
672#define ecs_const_var(world, ...)\
673 ecs_const_var_init(world, &(ecs_const_var_desc_t)__VA_ARGS__)
674
675/* Functions */
676
678 typedef struct ecs_function_desc_t {
680 const char *name;
681
684 ecs_entity_t parent;
685
687 ecs_script_parameter_t params[FLECS_SCRIPT_FUNCTION_ARGS_MAX];
688
690 ecs_entity_t return_type;
691
693 ecs_function_callback_t callback;
694
696 void *ctx;
697} ecs_function_desc_t;
698
706FLECS_API
707 ecs_entity_t ecs_function_init(
708 ecs_world_t *world,
709 const ecs_function_desc_t *desc);
710
711#define ecs_function(world, ...)\
712 ecs_function_init(world, &(ecs_function_desc_t)__VA_ARGS__)
713
726FLECS_API
727 ecs_entity_t ecs_method_init(
728 ecs_world_t *world,
729 const ecs_function_desc_t *desc);
730
731#define ecs_method(world, ...)\
732 ecs_method_init(world, &(ecs_function_desc_t)__VA_ARGS__)
733
734
735/* Value serialization */
736
746FLECS_API
747 char* ecs_ptr_to_expr(
748 const ecs_world_t *world,
749 ecs_entity_t type,
750 const void *data);
751
761FLECS_API
762 int ecs_ptr_to_expr_buf(
763 const ecs_world_t *world,
764 ecs_entity_t type,
765 const void *data,
766 ecs_strbuf_t *buf);
767
779FLECS_API
780 char* ecs_ptr_to_str(
781 const ecs_world_t *world,
782 ecs_entity_t type,
783 const void *data);
784
794FLECS_API
795 int ecs_ptr_to_str_buf(
796 const ecs_world_t *world,
797 ecs_entity_t type,
798 const void *data,
799 ecs_strbuf_t *buf);
800
801typedef struct ecs_expr_node_t ecs_expr_node_t;
802
811FLECS_API
812 void FlecsScriptImport(
813 ecs_world_t *world);
814
815#ifdef __cplusplus
816}
817#endif
818
819#endif
820
822
823#endif
ecs_script_runtime_free
FLECS_API void ecs_script_runtime_free(ecs_script_runtime_t *runtime)
Free script runtime.
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_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_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:106
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_run
FLECS_API int ecs_script_run(ecs_world_t *world, const char *name, const char *code)
Parse script.
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_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_eval
FLECS_API int ecs_script_eval(const ecs_script_t *script, const ecs_script_eval_desc_t *desc)
Evaluate 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_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:380
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:424
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:121
EcsScriptFunction
Function component.
Definition script.h:129
EcsScriptMethod
Method component.
Definition script.h:141
EcsScript
Script component.
Definition script.h:93
ecs_const_var_desc_t
Used with ecs_const_var_init.
Definition script.h:646
ecs_expr_eval_desc_t
Used with ecs_expr_run().
Definition script.h:542
ecs_expr_eval_desc_t::disable_folding
bool disable_folding
Disable constant folding (slower evaluation, faster parsing)
Definition script.h:554
ecs_expr_eval_desc_t::type
ecs_entity_t type
Type of parsed value (optional)
Definition script.h:546
ecs_expr_eval_desc_t::vars
const ecs_script_vars_t * vars
Variables accessible in expression.
Definition script.h:545
ecs_expr_eval_desc_t::runtime
ecs_script_runtime_t * runtime
Reusable runtime (optional)
Definition script.h:565
ecs_expr_eval_desc_t::allow_unresolved_identifiers
bool allow_unresolved_identifiers
Allow for unresolved identifiers when parsing.
Definition script.h:563
ecs_expr_eval_desc_t::name
const char * name
Script name.
Definition script.h:543
ecs_expr_eval_desc_t::expr
const char * expr
Full expression string.
Definition script.h:544
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:559
ecs_expr_eval_desc_t::lookup_ctx
void * lookup_ctx
Context passed to lookup function.
Definition script.h:551
ecs_function_ctx_t
Script function context.
Definition script.h:99
ecs_function_desc_t
Used with ecs_function_init and ecs_method_init.
Definition script.h:678
ecs_function_desc_t::return_type
ecs_entity_t return_type
Function return type.
Definition script.h:690
ecs_function_desc_t::name
const char * name
Function name.
Definition script.h:680
ecs_function_desc_t::params
ecs_script_parameter_t params[(16)]
Function parameters.
Definition script.h:687
ecs_function_desc_t::ctx
void * ctx
Context passed to function implementation.
Definition script.h:696
ecs_function_desc_t::callback
ecs_function_callback_t callback
Function implementation.
Definition script.h:693
ecs_function_desc_t::parent
ecs_entity_t parent
Parent of function.
Definition script.h:684
ecs_iter_t
Iterator.
Definition flecs.h:1135
ecs_script_desc_t
Used with ecs_script_init()
Definition script.h:296
ecs_script_eval_desc_t
Used with ecs_script_parse() and ecs_script_eval()
Definition script.h:151
ecs_script_eval_desc_t::runtime
ecs_script_runtime_t * runtime
Reusable runtime (optional)
Definition script.h:153
ecs_script_eval_desc_t::vars
ecs_script_vars_t * vars
Variables used by script.
Definition script.h:152
ecs_script_parameter_t
Function argument type.
Definition script.h:113
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:988
ecs_value_t
Utility to hold a value of a dynamic type.
Definition flecs.h:1002