Loading models and other complex data during flecs world deserialization

[WillNilges]

Hello! Loving Flecs and its excellent documentation so far. I had a question about how to handle loading complex data when deserializing flecs worlds back into my application.

I am working on a custom game engine (primarily as a learning pursuit). In it, I need to load models, configure the physics engine, etc. I think I am grasping how to serialize and deserialize basic nested structs (things like position, rotation). You need to define it with a macro like this. But for more complicated "stateful"(?) things such as models, I am loading them into memory as components and attaching them to entities. When I serialize, I don't want to serialize the model data into the json file, that'd be slow and inefficient. Instead, I'd like to serialize data that tells the engine how to re-import the model, or to find it within flecs if it's already imported.

I think what I need is a deserializing "hook" for certain components, so that flecs knows how to handle them. Is this possible today? Am I thinking about the problem correctly?

Another idea I just had while writing this: Maybe I could deserialize the world and then "lazy load" the models and everything else on the next frame?

Any input or advice is appreciated. Thank you!

[SanderMertens]

Take a look at hooks: https://www.flecs.dev/flecs/md_docs_2EntitiesComponents.html#hooks
and observers: https://www.flecs.dev/flecs/md_docs_2ObserversManual.html

You might also want to take a look at flecs script, which is a more feature-rich environment for describing the contents you want to load in a world: https://www.flecs.dev/flecs/md_docs_2FlecsScript.html

[SanderMertens]

An on_add hook triggers right after the component has been created in the storage, which is before it has been assigned. If you want to respond to an assigned value of the component, try using the on_set handler.

Also, small nit- you can shorten your struct definition in flecs script to:

struct transform.Position {
  x = f32
  y = f32
  z = f32
}

[WillNilges]

Oh derp, that totally worked. Thank you! I will continue working on implementing my scene loader and let you know if I have any more snags.

[WillNilges]

I think I might be misunderstanding something.

How is reflection data supposed to work? I have this type in my engine (from learnopengl)

typedef struct {
  vec3s direction;

  vec3s ambient;
  vec3s diffuse;
  vec3s specular;
} DirLight;

In my head, I'd like to treat this as a "component" that goes on an entity. But reading the docs and looking at the city example, it almost seems like DirLight is a component that... has other components (vec3s) inside of it?

Hence I'm not totally sure how to express this type in flecs script as reflection data, so there's that, but then that raises another question relating to the examples: It seems like city does not describe reflection data in flecs script, but somehow includes it from the C/C++ code (example). I am unsure how to replicate this (especially when city is using bake, which I'd like to avoid having another dependency). When I use an import function...

void LightsImport(ecs_world_t *world) {
  ECS_MODULE(world, Lights);

  ECS_COMPONENT_DEFINE(world, DirLight);
  ECS_COMPONENT_DEFINE(world, PointLight);
  ECS_COMPONENT_DEFINE(world, SpotLight);
}

and ECS_IMPORT(world, Lights); to import the module into my world, then doing this in flecs script

lights.DirLight imported_light1 (
    direction: { 0.5, 0.5, 0.5 }
    ambient: { 0.5, 0.5, 0.5 }
    diffuse: { 0.5, 0.5, 0.5 }
    specular: { 0.5, 0.5, 0.5 }
)

gives this error

error: cursor.c: 240: cannot open scope for 'lights.DirLight' (missing reflection data)
error: scene1.flecs: 34: missing type for initializer
lights.DirLight imported_light1 (
                               ^

I must be thinking about this wrong, because that DirLight definition above does not match anything on the docs page 😅

But anyway, what I'm trying to do is find a way to describe my types in C, and then write flecs script to load them, without having to repeat myself and describe the reflection data. Is this possible? Do I have this backwards?

Thanks again for all your help so far. I'm very new to the ECS way of thinking, but this stuff is very cool.

Edit: I think I figured out part of my issue. I had Position, Rotation, and Scale mapped out as type aliases to vec3s and versors. It was hard to map that in the reflection system, since it seemed like I had to do each one individually (today I feel like that's not actually true and I didn't know what I was doing earlier :P)

Anyway, now I have them mapped as a Transform struct, using the ECS_STRUCT macro and a bit of boilerplate from the city example. Works much better.

// Reflection system boilerplate
#undef ECS_META_IMPL
#ifndef TRANSFORM_IMPL
#define ECS_META_IMPL EXTERN // Ensure meta symbols are only defined once
#endif

ECS_STRUCT(Transform, {
  vec3s position;
  versors rotation;
  vec3s scale;
});

One issue I'll have to deal with later(tm) is that cimgui (my GUI lib) also defines a macro called EXTERN, which is causing some nasty compilation errors. Not certain what to do about that yet.

[SanderMertens]

But reading the docs and looking at the city example, it almost seems like DirLight is a component that... has other components (vec3s) inside of it?

What parts of the code make you say this? It is totally valid to have a single component with multiple struct/array members. This should be pretty straightforward as well, and is a pattern that's widely used in the modules used by the city example.

It seems like city does not describe reflection data in flecs script

Correct, the default approach is to register reflection data in code. It sounds like you may not have found the reflection examples yet, which provide a good overview of how you can do this: https://github.com/SanderMertens/flecs/tree/master/examples/c/reflection

You'll find both ways to register reflection manually with the API ecs_struct(world, { ... }) and automatically with the ECS_STRUCT macro, for example https://github.com/SanderMertens/flecs/blob/master/examples/c/reflection/auto_define_struct/src/main.c

[WillNilges]

Yes! Thank you 😄 I think I was just confused on the correct way to use the ECS_STRUCT macro. After a bit of refactoring yesterday, I think everything is working. I have a follow-up question, but I'll ask it in a separate discussion.