Snapshot Deserialization Output

[ben-zabloski]

Issue

When using the snapshot deserializer, is it expected to see empty component array elements set to NaN?

Description

When using the snapshot deserializer, component array elements that aren't populated with entity data will be populated with NaN when deserialized.

// Serialize...
const world1 = createWorld();
const Position1 = { x: f32([]), y: f32([]), r: f32([]) };
const Velocity1 = { x: f32([]), y: f32([]) };
const components1 = [Position1, Velocity1];

const entityId1 = addEntity(world1);
addComponents(world1, entityId1, [Position1]);

Position1.x[entityId1] = 1;
Position1.y[entityId1] = 2;

const entityId2 = addEntity(world1);
addComponents(world1, entityId2, [Velocity1]);

Velocity1.x[entityId2] = 3;
Velocity1.y[entityId2] = 4;

console.log('components1', components1.length);
console.log(components1);
// components1 2
// [
//   { x: [ <1 empty item>, 1 ], y: [ <1 empty item>, 2 ], r: [] },
//   { x: [ <2 empty items>, 3 ], y: [ <2 empty items>, 4 ] }
// ]

const snapshotSerializer = createSnapshotSerializer(world1, components1);

// Deserialize...
const world2 = createWorld();
const Position2 = { x: f32([]), y: f32([]) };
const Velocity2 = { x: f32([]), y: f32([]) };
const components2 = [Position2, Velocity2];

const snapshotDeserializer = createSnapshotDeserializer(
    world2,
    components2,
);

const serialized = snapshotSerializer();
const map = snapshotDeserializer(serialized);

console.log('components2', components2.length);
console.log(components2);
// components2 2
// [
//   { x: [ <1 empty item>, 1, NaN ], y: [ <1 empty item>, 2, NaN ], r: [ <1 empty item>, NaN, NaN ] },
//   { x: [ <1 empty item>, NaN, 3 ], y: [ <1 empty item>, NaN, 4 ] }
// ]

This isn't a big problem as anyone can write code to protect against NaN data, but that code can get verbose, or add function overhead by using utility methods to parse the data.

For example - if Physicsbody.angularDamping[entityId] is empty, undefined, or null, this could work:

bodyDef.angularDamping =
  PhysicsBody.angularDamping[entityId] ?? bodyDef.angularDamping;

If the value is NaN, code turns into this:

const value = PhysicsBody.angularDamping[entityId];
if (Number.isFinite(value)) {
  bodyDef.angularDamping = value;
}

Or maybe:

const value = PhysicsBody.angularDamping[entityId];
bodyDef.angularDamping =
  Number.isFinite(value) ? value : bodyDef.angularDamping;

Or perhaps:

bodyDef.angularDamping = parse(PhysicsBody.angularDamping[entityId]);

Alternatives

I probably should just write a utility that will work for reading and applying component data through a map!

Any suggestions would be welcome! 😊

[americanjeff]

Looking at your example I wonder does it matter that Position2 does not have all the same members as Position1?

[ben-zabloski]

Looking at your example I wonder does it matter that Position2 does not have all the same members as Position1?

It's definitely a mistake in my example, as you probably shouldn't have different component signatures (so-to-speak) when serializing/deserializing things, but values that aren't initialized, like where entity 1 has a position and no velocity or vice-versa for entity 2, the empty values are converted to NaN. It honestly might be totally fine because it's sort of true! An "empty" node is also not a number, but JavaScript doesn't treat NaN the same as an "empty" array node, which means I might need to parse data differently if it's local versus deserialized - or rather, I just need to have a utility to account for it.

I did end up making a mapping utility though:

export type MappingConfig<TSource> = {
  [K in keyof TSource]?:
    | string
    | {
        path: string;
        transform?: (
          val: TSource[K] extends (infer U)[] ? U : never,
        ) => unknown;
      };
};

/**
 * Maps ECS component data to a target object.
 * Protects against NaN values (treating them as unset).
 */
export function mapComponentData<
  TSource extends { [K in keyof TSource]: unknown[] },
>(
  target: Record<string, unknown>,
  source: TSource,
  entityId: number,
  config: MappingConfig<TSource>,
): void {
  for (const sourceKey in config) {
    const targetConfig = config[sourceKey];
    if (!targetConfig) continue;

    const componentValues = source[sourceKey];
    if (!componentValues) continue;

    const rawValue = componentValues[entityId];

    if (
      rawValue === undefined ||
      (typeof rawValue === 'number' && Number.isNaN(rawValue))
    ) {
      continue;
    }

    const path =
      typeof targetConfig === 'string' ? targetConfig : targetConfig.path;

    const transform =
      typeof targetConfig === 'object' && targetConfig !== null
        ? targetConfig.transform
        : undefined;

    const finalValue = transform ? transform(rawValue as never) : rawValue;

    setAt(target, path, finalValue);
  }
}

/**
 * Utility to set a value at a certain path in an object.
 * Supports nested paths and calling functions if the target is a function.
 */
export function setAt(
  obj: Record<string, unknown>,
  path: string,
  value: unknown,
): void {
  const parts = path.split('.');
  /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
  let current = obj as Record<string, any>;

  for (let i = 0; i < parts.length - 1; i++) {
    const part = parts[i];
    if (current[part] === undefined) {
      current[part] = {};
    }
    /* eslint-disable-next-line @typescript-eslint/no-explicit-any */
    current = current[part] as Record<string, any>;
  }

  const lastPart = parts[parts.length - 1];

  const target = current[lastPart];

  // If the target property is a function (like SetAngle), call it
  if (typeof target === 'function') {
    target.call(current, value);
  } else {
    current[lastPart] = value;
  }
}

That you use like this:

const bodyDef = b2DefaultBodyDef();

mapComponentData(bodyDef as any, PhysicsBody, entityId, {
  angularDamping: 'angularDamping',
  angularVelocity: 'angularVelocity',
  allowSleep: 'enableSleep',
  gravityScale: 'gravityScale',
  awake: 'isAwake',
  bullet: 'isBullet',
  enabled: 'isEnabled',
  fixedRotation: 'fixedRotation',
  linearDamping: 'linearDamping',
  linearVelocityX: 'linearVelocity.x',
  linearVelocityY: 'linearVelocity.y',
  positionX: 'position.x',
  positionY: 'position.y',
  angle: 'rotation.SetAngle',
  type: {
    path: 'type',
    transform: (value) => toB2BodyType(value as number, b2BodyType),
  },
});

Has some room for improvement though! 😁