Skip to content

Commit

Permalink
Add more builtin script functions, add documentation on builtin funct…
Browse files Browse the repository at this point in the history 
…ions
  • Loading branch information
@SanderMertens
SanderMertens committed Dec 15, 2024
1 parent 308a728 commit 0051026
Show file tree
Hide file tree
Showing 9 changed files with 696 additions and 107 deletions.
196 changes: 163 additions & 33 deletions distr/flecs.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55649,32 +55649,127 @@ void flecs_meta_entity_parent(
*(ecs_entity_t*)result->ptr = ecs_get_parent(ctx->world, entity);
}

#ifdef FLECS_DOC

static
void flecs_meta_entity_doc_name(
void flecs_meta_entity_has(
const ecs_function_ctx_t *ctx,
int32_t argc,
const ecs_value_t *argv,
ecs_value_t *result)
{
(void)argc;
ecs_entity_t entity = *(ecs_entity_t*)argv[0].ptr;
*(char**)result->ptr = ecs_os_strdup(ecs_doc_get_name(ctx->world, entity));
ecs_id_t id = *(ecs_id_t*)argv[1].ptr;
*(ecs_bool_t*)result->ptr = ecs_has_id(ctx->world, entity, id);
}

static
void flecs_meta_core_pair(
const ecs_function_ctx_t *ctx,
int32_t argc,
const ecs_value_t *argv,
ecs_value_t *result)
{
(void)argc;
(void)ctx;
ecs_entity_t first = *(ecs_entity_t*)argv[0].ptr;
ecs_entity_t second = *(ecs_entity_t*)argv[1].ptr;
*(ecs_id_t*)result->ptr = ecs_pair(first, second);
}

#ifdef FLECS_DOC

#define FLECS_DOC_FUNC(name)\
static\
void flecs_meta_entity_doc_##name(\
const ecs_function_ctx_t *ctx,\
int32_t argc,\
const ecs_value_t *argv,\
ecs_value_t *result)\
{\
(void)argc;\
ecs_entity_t entity = *(ecs_entity_t*)argv[0].ptr;\
*(char**)result->ptr = \
ecs_os_strdup(ecs_doc_get_##name(ctx->world, entity));\
}

FLECS_DOC_FUNC(name)
FLECS_DOC_FUNC(uuid)
FLECS_DOC_FUNC(brief)
FLECS_DOC_FUNC(detail)
FLECS_DOC_FUNC(link)
FLECS_DOC_FUNC(color)

#undef FLECS_DOC_FUNC

static
void flecs_script_register_builtin_doc_functions(
ecs_world_t *world)
{
ecs_entity_t name = ecs_method(world, {
.name = "doc_name",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_doc_name
});
{
ecs_entity_t m = ecs_method(world, {
.name = "doc_name",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_doc_name
});

ecs_doc_set_brief(world, m, "Returns entity doc name");
}

{
ecs_entity_t m = ecs_method(world, {
.name = "doc_uuid",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_doc_uuid
});

ecs_doc_set_brief(world, m, "Returns entity doc uuid");
}

{
ecs_entity_t m = ecs_method(world, {
.name = "doc_brief",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_doc_brief
});

ecs_doc_set_brief(world, m, "Returns entity doc brief description");
}

{
ecs_entity_t m = ecs_method(world, {
.name = "doc_detail",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_doc_detail
});

ecs_doc_set_brief(world, m, "Returns entity doc detailed description");
}

{
ecs_entity_t m = ecs_method(world, {
.name = "doc_link",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_doc_link
});

ecs_doc_set_brief(world, m, "Returns entity doc link");
}

ecs_doc_set_brief(world, name, "Returns entity doc name");
{
ecs_entity_t m = ecs_method(world, {
.name = "doc_color",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_doc_color
});

ecs_doc_set_brief(world, m, "Returns entity doc color");
}
}

#else
Expand All @@ -55691,32 +55786,67 @@ void flecs_script_register_builtin_doc_functions(
void flecs_script_register_builtin_functions(
ecs_world_t *world)
{
ecs_entity_t name = ecs_method(world, {
.name = "name",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_name
});
{
ecs_entity_t m = ecs_method(world, {
.name = "name",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_name
});

ecs_doc_set_brief(world, name, "Returns entity name");
ecs_doc_set_brief(world, m, "Returns entity name");
}

ecs_entity_t path = ecs_method(world, {
.name = "path",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_path
});
{
ecs_entity_t m = ecs_method(world, {
.name = "path",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_string_t),
.callback = flecs_meta_entity_path
});

ecs_doc_set_brief(world, path, "Returns entity path");
ecs_doc_set_brief(world, m, "Returns entity path");
}

ecs_entity_t parent = ecs_method(world, {
.name = "parent",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_entity_t),
.callback = flecs_meta_entity_parent
});
{
ecs_entity_t m = ecs_method(world, {
.name = "parent",
.parent = ecs_id(ecs_entity_t),
.return_type = ecs_id(ecs_entity_t),
.callback = flecs_meta_entity_parent
});

ecs_doc_set_brief(world, m, "Returns entity parent");
}

ecs_doc_set_brief(world, parent, "Returns entity parent");
{
ecs_entity_t m = ecs_method(world, {
.name = "has",
.parent = ecs_id(ecs_entity_t),
.params = {
{ .name = "component", .type = ecs_id(ecs_id_t) }
},
.return_type = ecs_id(ecs_bool_t),
.callback = flecs_meta_entity_has
});

ecs_doc_set_brief(world, m, "Returns whether entity has component");
}

{
ecs_entity_t m = ecs_function(world, {
.name = "pair",
.parent = ecs_entity(world, { .name = "core"}),
.params = {
{ .name = "first", .type = ecs_id(ecs_entity_t) },
{ .name = "second", .type = ecs_id(ecs_entity_t) }
},
.return_type = ecs_id(ecs_id_t),
.callback = flecs_meta_core_pair
});

ecs_doc_set_brief(world, m, "Returns a pair identifier");
}

flecs_script_register_builtin_doc_functions(world);
}
Expand Down Expand Up @@ -55902,7 +56032,7 @@ void FlecsScriptMathImport(

/* Exponential and logarithmic functions */
FLECS_MATH_FUNC_DEF_F64(exp, "Compute exponential function");
FLECS_MATH_FUNC_DEF_F64_F32(ldexp, "Generate value from significand and exponent");
FLECS_MATH_FUNC_DEF_F64_F32(ldexp, "Generate value from significant and exponent");
FLECS_MATH_FUNC_DEF_F64(log, "Compute natural logarithm");
FLECS_MATH_FUNC_DEF_F64(log10, "Compute common logarithm");
FLECS_MATH_FUNC_DEF_F64(exp2, "Compute binary exponential function");
Expand Down
22 changes: 6 additions & 16 deletions distr/flecs.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -136,27 +136,17 @@
*/
// #define FLECS_KEEP_ASSERT

/** \def FLECS_CPP_NO_AUTO_REGISTRATION
* When set, the C++ API will require that components are registered before they
* are used. This is useful in multithreaded applications, where components need
* to be registered beforehand, and to catch issues in projects where component
* registration is mandatory. Disabling automatic component registration also
* slightly improves performance.
* The C API is not affected by this feature.
*/
// #define FLECS_CPP_NO_AUTO_REGISTRATION

/** @def FLECS_CPP_NO_AUTO_REGISTRATION
* When set, the C++ API will require that components are registered before they
* are used. This is useful in multithreaded applications, where components need
* to be registered beforehand, and to catch issues in projects where component
* to be registered beforehand, and to catch issues in projects where component
* registration is mandatory. Disabling automatic component registration also
* slightly improves performance.
* The C API is not affected by this feature.
*/
// #define FLECS_CPP_NO_AUTO_REGISTRATION

/** \def FLECS_CUSTOM_BUILD
/** @def FLECS_CUSTOM_BUILD
* This macro lets you customize which addons to build flecs with.
* Without any addons Flecs is just a minimal ECS storage, but addons add
* features such as systems, scheduling and reflection. If an addon is disabled,
Expand Down Expand Up @@ -273,7 +263,7 @@
#define FLECS_ID_DESC_MAX (32)
#endif

/** \def FLECS_EVENT_DESC_MAX
/** @def FLECS_EVENT_DESC_MAX
* Maximum number of events in ecs_observer_desc_t */
#ifndef FLECS_EVENT_DESC_MAX
#define FLECS_EVENT_DESC_MAX (8)
Expand All @@ -283,19 +273,19 @@
* Maximum number of query variables per query */
#define FLECS_VARIABLE_COUNT_MAX (64)

/** \def FLECS_TERM_COUNT_MAX
/** @def FLECS_TERM_COUNT_MAX
* Maximum number of terms in queries. Should not exceed 64. */
#ifndef FLECS_TERM_COUNT_MAX
#define FLECS_TERM_COUNT_MAX 32
#endif

/** \def FLECS_TERM_ARG_COUNT_MAX
/** @def FLECS_TERM_ARG_COUNT_MAX
* Maximum number of arguments for a term. */
#ifndef FLECS_TERM_ARG_COUNT_MAX
#define FLECS_TERM_ARG_COUNT_MAX (16)
#endif

/** \def FLECS_QUERY_VARIABLE_COUNT_MAX
/** @def FLECS_QUERY_VARIABLE_COUNT_MAX
* Maximum number of query variables per query. Should not exceed 128. */
#ifndef FLECS_QUERY_VARIABLE_COUNT_MAX
#define FLECS_QUERY_VARIABLE_COUNT_MAX (64)
Expand Down
73 changes: 73 additions & 0 deletions docs/FlecsScript.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -957,6 +957,79 @@ ecs_method(world, {
});
```
### Builtin functions and constants
The following table lists builtin core functions in the `flecs.script.core` namespace:
| **Function Name** | **Description** | **Return Type** | **Arguments** |
|-------------------|-----------------------------|-----------------|-----------------------------|
| `pair` | Returns a pair identifier | `id` | (`entity`, `entity`) |
The following table lists builtin methods on the `flecs.meta.entity` type:
| **Method Name** | **Description** | **Return Type** | **Arguments** |
|-------------------|----------------------------------------|-----------------|----------------------|
| `name` | Returns entity name | `string` | `()` |
| `path` | Returns entity path | `string` | `()` |
| `parent` | Returns entity parent | `entity` | `()` |
| `has` | Returns whether entity has component | `bool` | `(id)` |
The following table lists doc methods on the `flecs.meta.entity` type:
| **Method Name** | **Description** | **Return Type** | **Arguments** |
|-------------------|------------------------------------------|------------------|----------------------|
| `doc_name` | Returns entity doc name | `string` | `()` |
| `doc_uuid` | Returns entity doc uuid | `string` | `()` |
| `doc_brief` | Returns entity doc brief description | `string` | `()` |
| `doc_detail` | Returns entity doc detailed description | `string` | `()` |
| `doc_link` | Returns entity doc link | `string` | `()` |
| `doc_color` | Returns entity doc color | `string` | `()` |
To use the doc functions, make sure to use a Flecs build compiled with `FLECS_DOC` (enabled by default).
The following table lists math functions in the `flecs.script.math` namespace:
| **Function Name** | **Description** | **Return Type** | **Arguments** |
|--------------------|-----------------------------------------|-----------------|---------------------|
| `cos` | Compute cosine | `f64` | `(f64)` |
| `sin` | Compute sine | `f64` | `(f64)` |
| `tan` | Compute tangent | `f64` | `(f64)` |
| `acos` | Compute arc cosine | `f64` | `(f64)` |
| `asin` | Compute arc sine | `f64` | `(f64)` |
| `atan` | Compute arc tangent | `f64` | `(f64)` |
| `atan2` | Compute arc tangent with two parameters | `f64` | `(f64, f64)` |
| `cosh` | Compute hyperbolic cosine | `f64` | `(f64)` |
| `sinh` | Compute hyperbolic sine | `f64` | `(f64)` |
| `tanh` | Compute hyperbolic tangent | `f64` | `(f64)` |
| `acosh` | Compute area hyperbolic cosine | `f64` | `(f64)` |
| `asinh` | Compute area hyperbolic sine | `f64` | `(f64)` |
| `atanh` | Compute area hyperbolic tangent | `f64` | `(f64)` |
| `exp` | Compute exponential function | `f64` | `(f64)` |
| `ldexp` | Generate value from significant and exponent | `f64` | `(f64, f32)` |
| `log` | Compute natural logarithm | `f64` | `(f64)` |
| `log10` | Compute common logarithm | `f64` | `(f64)` |
| `exp2` | Compute binary exponential function | `f64` | `(f64)` |
| `log2` | Compute binary logarithm | `f64` | `(f64)` |
| `pow` | Raise to power | `f64` | `(f64, f64)` |
| `sqrt` | Compute square root | `f64` | `(f64)` |
| `sqr` | Compute square | `f64` | `(f64)` |
| `ceil` | Round up value | `f64` | `(f64)` |
| `floor` | Round down value | `f64` | `(f64)` |
| `round` | Round to nearest | `f64` | `(f64)` |
| `abs` | Compute absolute value | `f64` | `(f64)` |
The following table lists the constants in the `flecs.script.math` namespace:
| **Function Name** | **Description** | **Type** | **Value** |
|-------------------|-------------------------------------------|----------|----------------------|
| `E` | Euler's number | `f64` | `2.71828182845904523536028747135266250` |
| `PI` | Ratio of circle circumference to diameter | `f64` | `3.14159265358979323846264338327950288` |
To use the math functions, make sure to use a Flecs build compiled with the `FLECS_SCRIPT_MATH` addon (disabled by default) and that the module is imported:
```c
ECS_IMPORT(world, FlecsScriptMath);
```

## Templates
Templates are parameterized scripts that can be used to create procedural assets. Templates can be created with the `template` keyword. Example:

Expand Down
Loading

0 comments on commit 0051026

Please sign in to comment.