Deserializing entities

[hw762]

What are some good ways to deserialize entities? For instance,

{
  // ...
  components: {
    "Hp": 100.0,
    "Damage": 10.0
  }
}

And when deserializing an entity like above, I should ideally create all the components correctly. However, I don't find a good way without hard coding a large when statement. Is there a better way to achieve this, maybe with reflections?

[Quillraven]

Have a look at world.loadSnapshotOf:

 fun loadSnapshotOf(entity: Entity, components: List<Component<*>>) {

You can pass in an entity and a list of components and Fleks will then correctly load it into the world and update families/systems/...

Let me know if that solves your problem!

edit: or do you mean how to transform your JSON back to components? That depends on what kind of serializing strategy/framework you are using.

In general, I'd try to avoid reflection since it is hard to debug and understand and can be slow. If you have a small amount of components/stored data then I'd simply start with a simple approach.

From LibGDX I know that you can easily serialize/deserialize any object. Have a look: https://libgdx.com/wiki/utils/reading-and-writing-json

With that plus the loadSnapshotOf function, you should be good to go. But again to be more precise I need to know how you are currently serializing/deserializing objects within your game.

[hw762]

I mean from Json to components. I am using kotlinx.serialization. Right now I am just doing a large when case, but there is a little code reuse I could do:

val ser = when (key) {
  "A" -> AComponent.serializer()
  "B" -> BComponent.serializer()
}
entity += listOf(Json.decodeFromJsonElement(ser, value))

I am not sure if I am reading the API right... for whatever reason, I have to construct a list for each individual component, instead of doing entity += component directly. entity is an Entity object in the world.entity context.

[Quillraven]

I think you can simply load the entire list of components. No need for your when statement. Since the functions takes a List<Componen<*>>, it is anyway "unsafe" for types and doesn't care about a specific component type.

I guess a simple cast from JSON to List<Component<*>> might be sufficient and then just load it.

I will make some examples on the weekend and post them here for discussion. Since it is a reoccurring topic, it will be a good idea to have examples in the wiki for that 😊

[hw762]

The when statement is used to decide which component it should serialize to. Actually, this is to save me from writing Json.decodeFromJsonElement for every case.

[Quillraven]

Okay, here is a quick example I made:

fun main() {
    val world = configureWorld { }
    val entity = world.entity {
        it += LifeComponent(life = 10f, max = 10f, regeneration = 2f)
        it += MoveComponent(speed = 3f)
    }

    with(Json()) {
        var components = world.snapshotOf(entity)
        val json = toJson(components)
        println(prettyPrint(json))

        world.removeAll()
        @Suppress("UNCHECKED_CAST")
        components = fromJson(List::class.java, json) as List<Component<*>>
        world.loadSnapshotOf(entity, components)
        println(world.snapshot())
    }
}

The created JSON is:

[
  {
	  class: com.github.quillraven.mysticwoods.component.MoveComponent
	  speed: 3
  }
  {
	  class: com.github.quillraven.mysticwoods.component.LifeComponent
	  life: 10
	  max: 10
	  regeneration: 2
  }
]

As you can see, there is no when statement needed. Just serialize the entire list of components. I guess it should work similar with kotlinx serialization. I used LibGDX's JSON class.

@jobe-m : can you please provide the example how you do it currently in KorGE?

[jobe-m]

Sure :)

I have implemented Serialization of the Fleks world in KorGE-Fleks for all components which I use/provide there.

There are a couple of unit tests which do serialization and deserialization of some components.

Serialization of a world snapshot works like that which can be found in CommonTestEnv.kt.
Serialization of a single Entity with associated components with snapshotOf() should work the same way.

val compactJson = snapshotSerializer.json().encodeToString(worldIn.snapshot() as SerializableSnapshot)

And so does deserialization:

val snapshotFromJson = snapshotSerializer.json().decodeFromString<SerializableSnapshot>(compactJson)
worldOut.loadSnapshot(snapshotFromJson as FleksSnapshot)

SnapshotSerializer is a convenience class to get a json serializer which has all needed serializer modules. Details can be found in this file.
The trick with serializing Fleks components in kotlinx.serialization is to use a polymorphic serializer and an interface class (here: SerializeBase) which all components needs to derive from. Because of ambiguity of the star-projection in the returned map of world.snapshot() Component<*> cannot be used as a base for the polymorphic serialization. So the added inferface class is needed:

E.g. the Sprite component of KorGe-Fleks looks like that:

@Serializable
@SerialName("Sprite")
data class Sprite(
    var assetName: String = "",
    var animationName: String? = null,
    var isPlaying: Boolean = false,
    var forwardDirection: Boolean = true,
    var loop: Boolean = false,
    var destroyOnPlayingFinished: Boolean = true,
) : Component<Sprite>, SerializeBase {
    override fun type(): ComponentType<Sprite> = Sprite
    companion object : ComponentType<Sprite>()
}

This here is an example of the JSON file for my game object "Spaceship" which has a couple of sub-entities for different things. "type" below is the name of the component class.

"173": [
        {
            "type": "SubEntities",
            "entities": {
                "fireball_white_fire": 174,
                "fireball_fire_trail_A": 175,
                "fireball_fire_trail_B": 176,
                "fireball_fire_trail_C": 177,
                "spaceship_shield": 178,
                "spaceship_right_wing_dust_spawner": 179,
                "spaceship_left_wing_dust_spawner": 180,
                "spaceship_drive_dust_spawner": 181,
                "spaceship_drive_charge": 182,
                "spaceship_drive_fire": 183
            }
        },
        {
            "type": "LifeCycle"
        },
        {
            "type": "Sprite",
            "assetName": "spaceship",
            "animationName": "horizontal_to_top",
            "destroyOnPlayingFinished": false
        },
        {
            "type": "Offset",
            "x": 52.0,
            "y": 45.0
        },
        {
            "type": "Appearance"
        },
        {
            "type": "PositionShape",
            "x": 80.0,
            "y": 180.0,
            "width": 80.0,
            "height": 60.0
        },
        {
            "type": "Drawable",
            "drawOnLayer": "play_field_layer_3"
        }
    ]

[Quillraven]

I finally had some time to add the wiki page for serialization: https://github.com/Quillraven/Fleks/wiki/Serialization

Hope this helps future folks coming here! ;)