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
27#ifndef FLECS_SCRIPT_H
28#define FLECS_SCRIPT_H
29
30#ifdef __cplusplus
31extern "C" {
32#endif
33
34#define FLECS_SCRIPT_FUNCTION_ARGS_MAX (16)
35
36FLECS_API
37extern ECS_COMPONENT_DECLARE(EcsScript);
38
39FLECS_API
40extern ECS_DECLARE(EcsScriptTemplate);
41
42FLECS_API
43extern ECS_COMPONENT_DECLARE(EcsScriptConstVar);
44
45FLECS_API
46extern ECS_COMPONENT_DECLARE(EcsScriptFunction);
47
48FLECS_API
49extern ECS_COMPONENT_DECLARE(EcsScriptMethod);
50
51/* Script template. */
52typedef struct ecs_script_template_t ecs_script_template_t;
53
55 typedef struct ecs_script_var_t {
56 const char *name;
57 ecs_value_t value;
58 const ecs_type_info_t *type_info;
59 int32_t sp;
60 bool is_const;
61} ecs_script_var_t;
62
64 typedef struct ecs_script_vars_t {
65 struct ecs_script_vars_t *parent;
66 int32_t sp;
67
68 ecs_hashmap_t var_index;
69 ecs_vec_t vars;
70
71 const ecs_world_t *world;
72 struct ecs_stack_t *stack;
73 ecs_stack_cursor_t *cursor;
74 ecs_allocator_t *allocator;
75} ecs_script_vars_t;
76
78 typedef struct ecs_script_t {
79 ecs_world_t *world;
80 const char *name;
81 const char *code;
82} ecs_script_t;
83
84/* Runtime for executing scripts */
85typedef struct ecs_script_runtime_t ecs_script_runtime_t;
86
90 typedef struct EcsScript {
91 ecs_script_t *script;
92 ecs_script_template_t *template_; /* Only set for template scripts */
93} EcsScript;
94
96 typedef struct ecs_function_ctx_t {
97 ecs_world_t *world;
98 ecs_entity_t function;
99 void *ctx;
100} ecs_function_ctx_t;
101
103 typedef void(*ecs_function_callback_t)(
104 const ecs_function_ctx_t *ctx,
105 int32_t argc,
106 const ecs_value_t *argv,
107 ecs_value_t *result);
108
110 typedef struct ecs_script_parameter_t {
111 const char *name;
112 ecs_entity_t type;
113} ecs_script_parameter_t;
114
118 typedef struct EcsScriptConstVar {
119 ecs_value_t value;
120 const ecs_type_info_t *type_info;
121} EcsScriptConstVar;
122
126 typedef struct EcsScriptFunction {
127 ecs_entity_t return_type;
128 ecs_vec_t params; /* vec<ecs_script_parameter_t> */
129 ecs_function_callback_t callback;
130 void *ctx;
131} EcsScriptFunction;
132
138 typedef struct EcsScriptMethod {
139 ecs_entity_t return_type;
140 ecs_vec_t params; /* vec<ecs_script_parameter_t> */
141 ecs_function_callback_t callback;
142 void *ctx;
143} EcsScriptMethod;
144
145/* Parsing & running scripts */
146
148 typedef struct ecs_script_eval_desc_t {
149 ecs_script_vars_t *vars;
150 ecs_script_runtime_t *runtime;
151} ecs_script_eval_desc_t;
152
167FLECS_API
168 ecs_script_t* ecs_script_parse(
169 ecs_world_t *world,
170 const char *name,
171 const char *code,
172 const ecs_script_eval_desc_t *desc);
173
185FLECS_API
186 int ecs_script_eval(
187 const ecs_script_t *script,
188 const ecs_script_eval_desc_t *desc);
189
199FLECS_API
200 void ecs_script_free(
201 ecs_script_t *script);
202
218FLECS_API
219 int ecs_script_run(
220 ecs_world_t *world,
221 const char *name,
222 const char *code);
223
233FLECS_API
234 int ecs_script_run_file(
235 ecs_world_t *world,
236 const char *filename);
237
251FLECS_API
252ecs_script_runtime_t* ecs_script_runtime_new(void);
253
259FLECS_API
260 void ecs_script_runtime_free(
261 ecs_script_runtime_t *runtime);
262
271FLECS_API
272 int ecs_script_ast_to_buf(
273 ecs_script_t *script,
274 ecs_strbuf_t *buf,
275 bool colors);
276
284FLECS_API
285 char* ecs_script_ast_to_str(
286 ecs_script_t *script,
287 bool colors);
288
289
290/* Managed scripts (script associated with entity that outlives the function) */
291
293 typedef struct ecs_script_desc_t {
294 ecs_entity_t entity; /* Set to customize entity handle associated with script */
295 const char *filename; /* Set to load script from file */
296 const char *code; /* Set to parse script from string */
297} ecs_script_desc_t;
298
309FLECS_API
310 ecs_entity_t ecs_script_init(
311 ecs_world_t *world,
312 const ecs_script_desc_t *desc);
313
314#define ecs_script(world, ...)\
315 ecs_script_init(world, &(ecs_script_desc_t) __VA_ARGS__)
316
324FLECS_API
325 int ecs_script_update(
326 ecs_world_t *world,
327 ecs_entity_t script,
328 ecs_entity_t instance,
329 const char *code);
330
337FLECS_API
338 void ecs_script_clear(
339 ecs_world_t *world,
340 ecs_entity_t script,
341 ecs_entity_t instance);
342
343
344/* Script variables */
345
362FLECS_API
363 ecs_script_vars_t* ecs_script_vars_init(
364 ecs_world_t *world);
365
372FLECS_API
373 void ecs_script_vars_fini(
374 ecs_script_vars_t *vars);
375
387FLECS_API
388 ecs_script_vars_t* ecs_script_vars_push(
389 ecs_script_vars_t *parent);
390
399FLECS_API
400 ecs_script_vars_t* ecs_script_vars_pop(
401 ecs_script_vars_t *vars);
402
415FLECS_API
416 ecs_script_var_t* ecs_script_vars_declare(
417 ecs_script_vars_t *vars,
418 const char *name);
419
435FLECS_API
436 ecs_script_var_t* ecs_script_vars_define_id(
437 ecs_script_vars_t *vars,
438 const char *name,
439 ecs_entity_t type);
440
441#define ecs_script_vars_define(vars, name, type)\
442 ecs_script_vars_define_id(vars, name, ecs_id(type))
443
453FLECS_API
454 ecs_script_var_t* ecs_script_vars_lookup(
455 const ecs_script_vars_t *vars,
456 const char *name);
457
470FLECS_API
471 ecs_script_var_t* ecs_script_vars_from_sp(
472 const ecs_script_vars_t *vars,
473 int32_t sp);
474
480FLECS_API
481 void ecs_script_vars_print(
482 const ecs_script_vars_t *vars);
483
492FLECS_API
493 void ecs_script_vars_set_size(
494 ecs_script_vars_t *vars,
495 int32_t count);
496
529FLECS_API
530 void ecs_script_vars_from_iter(
531 const ecs_iter_t *it,
532 ecs_script_vars_t *vars,
533 int offset);
534
535
536/* Standalone expression evaluation */
537
539 typedef struct ecs_expr_eval_desc_t {
540 const char *name;
541 const char *expr;
542 const ecs_script_vars_t *vars;
543 ecs_entity_t type;
544 ecs_entity_t (*lookup_action)(
545 const ecs_world_t*,
546 const char *value,
547 void *ctx);
548 void *lookup_ctx;
549
551 bool disable_folding;
552
556 bool disable_dynamic_variable_binding;
557
560 bool allow_unresolved_identifiers;
561
562 ecs_script_runtime_t *runtime;
563} ecs_expr_eval_desc_t;
564
579FLECS_API
580 const char* ecs_expr_run(
581 ecs_world_t *world,
582 const char *ptr,
583 ecs_value_t *value,
584 const ecs_expr_eval_desc_t *desc);
585
595FLECS_API
596 ecs_script_t* ecs_expr_parse(
597 ecs_world_t *world,
598 const char *expr,
599 const ecs_expr_eval_desc_t *desc);
600
615FLECS_API
616 int ecs_expr_eval(
617 const ecs_script_t *script,
618 ecs_value_t *value,
619 const ecs_expr_eval_desc_t *desc);
620
633FLECS_API
634 char* ecs_script_string_interpolate(
635 ecs_world_t *world,
636 const char *str,
637 const ecs_script_vars_t *vars);
638
639
640/* Global const variables */
641
643 typedef struct ecs_const_var_desc_t {
644 /* Variable name. */
645 const char *name;
646
647 /* Variable parent (namespace). */
648 ecs_entity_t parent;
649
650 /* Variable type. */
651 ecs_entity_t type;
652
653 /* Pointer to value of variable. The value will be copied to an internal
654 * storage and does not need to be kept alive. */
655 void *value;
656} ecs_const_var_desc_t;
657
664FLECS_API
665 ecs_entity_t ecs_const_var_init(
666 ecs_world_t *world,
667 ecs_const_var_desc_t *desc);
668
669#define ecs_const_var(world, ...)\
670 ecs_const_var_init(world, &(ecs_const_var_desc_t)__VA_ARGS__)
671
672/* Functions */
673
675 typedef struct ecs_function_desc_t {
677 const char *name;
678
681 ecs_entity_t parent;
682
684 ecs_script_parameter_t params[FLECS_SCRIPT_FUNCTION_ARGS_MAX];
685
687 ecs_entity_t return_type;
688
690 ecs_function_callback_t callback;
691
693 void *ctx;
694} ecs_function_desc_t;
695
703FLECS_API
704 ecs_entity_t ecs_function_init(
705 ecs_world_t *world,
706 const ecs_function_desc_t *desc);
707
708#define ecs_function(world, ...)\
709 ecs_function_init(world, &(ecs_function_desc_t)__VA_ARGS__)
710
723FLECS_API
724 ecs_entity_t ecs_method_init(
725 ecs_world_t *world,
726 const ecs_function_desc_t *desc);
727
728#define ecs_method(world, ...)\
729 ecs_method_init(world, &(ecs_function_desc_t)__VA_ARGS__)
730
731
732/* Value serialization */
733
743FLECS_API
744 char* ecs_ptr_to_expr(
745 const ecs_world_t *world,
746 ecs_entity_t type,
747 const void *data);
748
758FLECS_API
759 int ecs_ptr_to_expr_buf(
760 const ecs_world_t *world,
761 ecs_entity_t type,
762 const void *data,
763 ecs_strbuf_t *buf);
764
776FLECS_API
777 char* ecs_ptr_to_str(
778 const ecs_world_t *world,
779 ecs_entity_t type,
780 const void *data);
781
791FLECS_API
792 int ecs_ptr_to_str_buf(
793 const ecs_world_t *world,
794 ecs_entity_t type,
795 const void *data,
796 ecs_strbuf_t *buf);
797
798typedef struct ecs_expr_node_t ecs_expr_node_t;
799
808FLECS_API
809 void FlecsScriptImport(
810 ecs_world_t *world);
811
812#ifdef __cplusplus
813}
814#endif
815
816#endif
817
819
820#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:103
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:346
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:390
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:118
EcsScriptFunction
Function component.
Definition script.h:126
EcsScriptMethod
Method component.
Definition script.h:138
EcsScript
Script component.
Definition script.h:90
ecs_const_var_desc_t
Used with ecs_const_var_init.
Definition script.h:643
ecs_expr_eval_desc_t
Used with ecs_expr_run().
Definition script.h:539
ecs_expr_eval_desc_t::disable_folding
bool disable_folding
Disable constant folding (slower evaluation, faster parsing)
Definition script.h:551
ecs_expr_eval_desc_t::type
ecs_entity_t type
Type of parsed value (optional)
Definition script.h:543
ecs_expr_eval_desc_t::vars
const ecs_script_vars_t * vars
Variables accessible in expression.
Definition script.h:542
ecs_expr_eval_desc_t::runtime
ecs_script_runtime_t * runtime
Reusable runtime (optional)
Definition script.h:562
ecs_expr_eval_desc_t::allow_unresolved_identifiers
bool allow_unresolved_identifiers
Allow for unresolved identifiers when parsing.
Definition script.h:560
ecs_expr_eval_desc_t::name
const char * name
Script name.
Definition script.h:540
ecs_expr_eval_desc_t::expr
const char * expr
Full expression string.
Definition script.h:541
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:556
ecs_expr_eval_desc_t::lookup_ctx
void * lookup_ctx
Context passed to lookup function.
Definition script.h:548
ecs_function_ctx_t
Script function context.
Definition script.h:96
ecs_function_desc_t
Used with ecs_function_init and ecs_method_init.
Definition script.h:675
ecs_function_desc_t::return_type
ecs_entity_t return_type
Function return type.
Definition script.h:687
ecs_function_desc_t::name
const char * name
Function name.
Definition script.h:677
ecs_function_desc_t::params
ecs_script_parameter_t params[(16)]
Function parameters.
Definition script.h:684
ecs_function_desc_t::ctx
void * ctx
Context passed to function implementation.
Definition script.h:693
ecs_function_desc_t::callback
ecs_function_callback_t callback
Function implementation.
Definition script.h:690
ecs_function_desc_t::parent
ecs_entity_t parent
Parent of function.
Definition script.h:681
ecs_iter_t
Iterator.
Definition flecs.h:1099
ecs_script_desc_t
Used with ecs_script_init()
Definition script.h:293
ecs_script_eval_desc_t
Used with ecs_script_parse() and ecs_script_eval()
Definition script.h:148
ecs_script_eval_desc_t::runtime
ecs_script_runtime_t * runtime
Reusable runtime (optional)
Definition script.h:150
ecs_script_eval_desc_t::vars
ecs_script_vars_t * vars
Variables used by script.
Definition script.h:149
ecs_script_parameter_t
Function argument type.
Definition script.h:110
ecs_script_t
Script object.
Definition script.h:78
ecs_script_var_t
Script variable.
Definition script.h:55
ecs_script_vars_t
Script variable scope.
Definition script.h:64
ecs_type_info_t
Type that contains component information (passed to ctors/dtors/...)
Definition flecs.h:953
ecs_value_t
Utility to hold a value of a dynamic type.
Definition flecs.h:966