script.h

Go to the documentation of this file.

 
#ifdef FLECS_SCRIPT
 
#ifndef FLECS_META
#define FLECS_META
#endif
 
#ifndef FLECS_DOC
#define FLECS_DOC
#endif
 
 
#ifndef FLECS_SCRIPT_H
#define FLECS_SCRIPT_H
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define FLECS_SCRIPT_FUNCTION_ARGS_MAX (16)
 
FLECS_API
extern ECS_COMPONENT_DECLARE(EcsScript);
 
FLECS_API
extern ECS_DECLARE(EcsScriptTemplate);
 
FLECS_API
extern ECS_COMPONENT_DECLARE(EcsScriptConstVar);
 
FLECS_API
extern ECS_COMPONENT_DECLARE(EcsScriptFunction);
 
FLECS_API
extern ECS_COMPONENT_DECLARE(EcsScriptMethod);
 
/* Script template. */
typedef struct ecs_script_template_t ecs_script_template_t;
 
typedef struct ecs_script_var_t {
    const char *name;
    ecs_value_t value;
    const ecs_type_info_t *type_info;
    bool is_const;
} ecs_script_var_t;
 
typedef struct ecs_script_vars_t {
    struct ecs_script_vars_t *parent;
    ecs_hashmap_t var_index;
    ecs_vec_t vars;
 
    const ecs_world_t *world;
    struct ecs_stack_t *stack;
    ecs_stack_cursor_t *cursor;
    ecs_allocator_t *allocator;
} ecs_script_vars_t;
 
typedef struct ecs_script_t {
    ecs_world_t *world;
    const char *name;
    const char *code;
} ecs_script_t;
 
/* Runtime for executing scripts */
typedef struct ecs_script_runtime_t ecs_script_runtime_t;
 
typedef struct EcsScript {
    ecs_script_t *script;
    ecs_script_template_t *template_; /* Only set for template scripts */
} EcsScript;
 
typedef struct ecs_function_ctx_t {
    ecs_world_t *world;
    ecs_entity_t function;
    void *ctx;
} ecs_function_ctx_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);
 
typedef struct ecs_script_parameter_t {
    const char *name;
    ecs_entity_t type;
} ecs_script_parameter_t;
 
typedef struct EcsScriptConstVar {
    ecs_value_t value;
    const ecs_type_info_t *type_info;
} EcsScriptConstVar;
 
typedef struct EcsScriptFunction {
    ecs_entity_t return_type;
    ecs_vec_t params; /* vec<ecs_script_parameter_t> */
    ecs_function_callback_t callback;
    void *ctx;
} EcsScriptFunction;
 
typedef struct EcsScriptMethod {
    ecs_entity_t return_type;
    ecs_vec_t params; /* vec<ecs_script_parameter_t> */
    ecs_function_callback_t callback;
    void *ctx;
} EcsScriptMethod;
 
/* Parsing & running scripts */
 
typedef struct ecs_script_eval_desc_t {
    ecs_script_vars_t *vars;       
    ecs_script_runtime_t *runtime; 
} ecs_script_eval_desc_t;
 
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);
 
FLECS_API
int ecs_script_eval(
    const ecs_script_t *script,
    const ecs_script_eval_desc_t *desc);
 
FLECS_API
void ecs_script_free(
    ecs_script_t *script);
 
FLECS_API
int ecs_script_run(
    ecs_world_t *world,
    const char *name,
    const char *code);
 
FLECS_API
int ecs_script_run_file(
    ecs_world_t *world,
    const char *filename);
 
FLECS_API
ecs_script_runtime_t* ecs_script_runtime_new(void);
 
FLECS_API
void ecs_script_runtime_free(
    ecs_script_runtime_t *runtime);
 
FLECS_API
int ecs_script_ast_to_buf(
    ecs_script_t *script,
    ecs_strbuf_t *buf,
    bool colors);
 
FLECS_API
char* ecs_script_ast_to_str(
    ecs_script_t *script,
    bool colors);
 
 
/* Managed scripts (script associated with entity that outlives the function) */
 
typedef struct ecs_script_desc_t {
    ecs_entity_t entity;   /* Set to customize entity handle associated with script */
    const char *filename;  /* Set to load script from file */
    const char *code;      /* Set to parse script from string */
} ecs_script_desc_t;
 
FLECS_API
ecs_entity_t ecs_script_init(
    ecs_world_t *world,
    const ecs_script_desc_t *desc);
 
#define ecs_script(world, ...)\
    ecs_script_init(world, &(ecs_script_desc_t) __VA_ARGS__)
 
FLECS_API
int ecs_script_update(
    ecs_world_t *world,
    ecs_entity_t script,
    ecs_entity_t instance,
    const char *code);
 
FLECS_API
void ecs_script_clear(
    ecs_world_t *world,
    ecs_entity_t script,
    ecs_entity_t instance);
 
 
/* Script variables */
 
FLECS_API
ecs_script_vars_t* ecs_script_vars_init(
    ecs_world_t *world);
 
FLECS_API
void ecs_script_vars_fini(
    ecs_script_vars_t *vars);
 
FLECS_API
ecs_script_vars_t* ecs_script_vars_push(
    ecs_script_vars_t *parent);
 
FLECS_API
ecs_script_vars_t* ecs_script_vars_pop(
    ecs_script_vars_t *vars);
 
FLECS_API
ecs_script_var_t* ecs_script_vars_declare(
    ecs_script_vars_t *vars,
    const char *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 ecs_script_vars_define(vars, name, type)\
    ecs_script_vars_define_id(vars, name, ecs_id(type))
 
FLECS_API
ecs_script_var_t* ecs_script_vars_lookup(
    const ecs_script_vars_t *vars,
    const char *name);
 
FLECS_API
void ecs_script_vars_from_iter(
    const ecs_iter_t *it,
    ecs_script_vars_t *vars,
    int offset);
 
 
/* Standalone expression evaluation */
 
typedef struct ecs_expr_eval_desc_t {
    const char *name;                
    const char *expr;                
    ecs_entity_t (*lookup_action)(   
        const ecs_world_t*,
        const char *value,
        void *ctx);
    void *lookup_ctx;                
    const ecs_script_vars_t *vars;   
    ecs_entity_t type;               
    /* Disable constant folding (slower evaluation, faster parsing) */
    bool disable_folding;
    
    /* Allow for unresolved identifiers when parsing. Useful when entities can
     * be created in between parsing & evaluating. */
    bool allow_unresolved_identifiers;
 
    ecs_script_runtime_t *runtime;   
} ecs_expr_eval_desc_t;
 
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);
 
FLECS_API
ecs_script_t* ecs_expr_parse(
    ecs_world_t *world,
    const char *expr,
    const ecs_expr_eval_desc_t *desc);
 
FLECS_API
int ecs_expr_eval(
    const ecs_script_t *script,
    ecs_value_t *value,
    const ecs_expr_eval_desc_t *desc);
 
FLECS_API
char* ecs_script_string_interpolate(
    ecs_world_t *world,
    const char *str,
    const ecs_script_vars_t *vars);
 
 
/* Global const variables */
 
typedef struct ecs_const_var_desc_t {
    /* Variable name. */
    const char *name;
 
    /* Variable parent (namespace). */
    ecs_entity_t parent;
 
    /* Variable type. */
    ecs_entity_t type;
 
    /* Pointer to value of variable. The value will be copied to an internal
     * storage and does not need to be kept alive. */
    void *value;
} ecs_const_var_desc_t;
 
FLECS_API
ecs_entity_t ecs_const_var_init(
    ecs_world_t *world,
    ecs_const_var_desc_t *desc);
 
#define ecs_const_var(world, ...)\
    ecs_const_var_init(world, &(ecs_const_var_desc_t)__VA_ARGS__)
 
/* Functions */
 
typedef struct ecs_function_desc_t {
    const char *name;
    
    ecs_entity_t parent;
 
    ecs_script_parameter_t params[FLECS_SCRIPT_FUNCTION_ARGS_MAX];
 
    ecs_entity_t return_type;
 
    ecs_function_callback_t callback;
 
    void *ctx;
} ecs_function_desc_t;
 
FLECS_API
ecs_entity_t ecs_function_init(
    ecs_world_t *world,
    const ecs_function_desc_t *desc);
 
#define ecs_function(world, ...)\
    ecs_function_init(world, &(ecs_function_desc_t)__VA_ARGS__)
 
FLECS_API
ecs_entity_t ecs_method_init(
    ecs_world_t *world,
    const ecs_function_desc_t *desc);
 
#define ecs_method(world, ...)\
    ecs_method_init(world, &(ecs_function_desc_t)__VA_ARGS__)
 
 
/* Value serialization */
 
FLECS_API
char* ecs_ptr_to_expr(
    const ecs_world_t *world,
    ecs_entity_t type,
    const void *data);
 
FLECS_API
int ecs_ptr_to_expr_buf(
    const ecs_world_t *world,
    ecs_entity_t type,
    const void *data,
    ecs_strbuf_t *buf);
 
FLECS_API
char* ecs_ptr_to_str(
    const ecs_world_t *world,
    ecs_entity_t type,
    const void *data);
 
FLECS_API
int ecs_ptr_to_str_buf(
    const ecs_world_t *world,
    ecs_entity_t type,
    const void *data,
    ecs_strbuf_t *buf);
 
typedef struct ecs_expr_node_t ecs_expr_node_t; 
 
FLECS_API
void FlecsScriptImport(
    ecs_world_t *world);
 
#ifdef __cplusplus
}
#endif
 
#endif
 
#endif