@driftengine/entities 4.7.2 → 4.7.4

package/dist/index.d.ts

@@ -16,7 +16,7 @@
  * and a future inspector all read **one** description of a component, so there is no second one to
  * keep in sync.
  */
-export type { ComponentStoreOptions, ComponentType, StoreSnapshot } from './store.ts';
+export type { ComponentDefault, ComponentStoreOptions, ComponentType, StoreSnapshot, } from './store.ts';
 export { ComponentStore, createStoreSnapshot, defineComponent } from './store.ts';
 export type { ComponentView, ViewColumn } from './view.ts';
 export type { CursorHost } from './query.ts';

package/dist/scene.js

@@ -108,9 +108,11 @@ export function deserializeWorld(world, scene, types) {
             const instance = {};
             for (const field of from.fields)
                 instance[field.name] = saved[field.id];
+            /* A field the file does not have takes the value the component declares for it, and zero or
+               nothing where it declares none. */
             const defaults = {};
             for (const field of type.schema.fields)
-                defaults[field.name] = field.type === 'String' ? null : 0;
+                defaults[field.name] = type.defaults[field.name] ?? (field.type === 'String' ? null : 0);
             const result = migrate(instance, from, type.schema, defaults);
             if (!result.migrated)
                 return { loaded: false, reason: result.reason };

package/dist/schedule.js

@@ -77,7 +77,7 @@ function group(order) {
     const groups = [];
     let current = [];
     for (const system of order) {
-        if (current.length > 0 && current.some((other) => conflicts(other, system))) {
+        if (current.some((other) => conflicts(other, system))) {
             groups.push(current);
             current = [];
         }

package/dist/store.d.ts

@@ -65,8 +65,20 @@ export interface ComponentType {
     readonly id: number;
     /** Fields typed `Entity`, which a scene load has to rewrite through its id map. */
     readonly entityFields: readonly string[];
+    /**
+     * The value each field was declared with, by field name; a field with none is absent and starts
+     * at zero, `false` or nothing.
+     *
+     * **Read wherever a field is not given**: an entity added with some of its fields, a prefab that
+     * names a few, a saved scene from before the field existed. A DriftScript component's come from
+     * the module's metadata (`seed: u32 = 7`); before they were read, every one of those paths
+     * filled zero and nothing said so.
+     */
+    readonly defaults: Readonly<Record<string, ComponentDefault>>;
 }
-export declare function defineComponent(schema: Schema): ComponentType;
+/** A field's declared value: a number for every numeric and enum column, a flag, or a string. */
+export type ComponentDefault = number | string | boolean;
+export declare function defineComponent(schema: Schema, defaults?: Readonly<Record<string, ComponentDefault>>): ComponentType;
 export declare function defineComponent(name: string, fields: Readonly<Record<string, string>>): ComponentType;
 /**
  * One store's contents, for a rewind. Reused between saves; see `AllocatorSnapshot`.

package/dist/store.js

@@ -105,7 +105,13 @@ let nextComponentId = 0;
  * caller wanting a different id scheme, at which point the id belongs entirely to whoever declares
  * the field and this function stops building one at all.
  */
-export function defineComponent(first, fields) {
+export function defineComponent(first, second) {
+    const fields = typeof first === 'string'
+        ? second
+        : undefined;
+    const defaults = typeof first === 'string'
+        ? {}
+        : (second ?? {});
     const schema = typeof first === 'string'
         ? {
             name: first,
@@ -125,10 +131,26 @@ export function defineComponent(first, fields) {
                 'about layout, so it is added here rather than assumed.');
         }
     }
+    /* A default names a field and fits its column, or the type is refused here, where a wrong one
+       is a fault in whoever declared it and not a value some later entity quietly starts with. */
+    for (const [name, value] of Object.entries(defaults)) {
+        const field = schema.fields.find((candidate) => candidate.name === name);
+        if (field === undefined) {
+            throw new Error(`\`${schema.name}\` has a default for \`${name}\`, which is not one of its fields: ` +
+                `${schema.fields.map((f) => `\`${f.name}\``).join(', ')}.`);
+        }
+        const inner = optionInner(field.type) ?? field.type;
+        const wanted = inner === 'String' ? 'string' : inner === 'bool' ? 'boolean' : 'number';
+        if (typeof value !== wanted) {
+            throw new Error(`\`${schema.name}.${name}\` is \`${field.type}\` and its default is the ${typeof value} ` +
+                `${JSON.stringify(value)}.`);
+        }
+    }
     return {
         name: schema.name,
         id: nextComponentId++,
         schema,
+        defaults: { ...defaults },
         /* An optional handle is still a handle, so a scene load has to rewrite it through the id map
            exactly as it rewrites a required one. Leaving it out would serialise a handle into a world
            whose indices mean something else. */
@@ -242,7 +264,9 @@ export class ComponentStore {
             const column = this.columns.get(field.name);
             if (column === undefined)
                 continue;
-            const given = values[field.name];
+            /* Omitted takes the declared value; a `null` given for an optional field is its absence. */
+            const own = values[field.name];
+            const given = own === undefined ? this.type.defaults[field.name] : own;
             if (Array.isArray(column))
                 column[at] = given ?? null;
             else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@driftengine/entities",
-  "version": "4.7.2",
+  "version": "4.7.4",
   "description": "Entities with generational identity, component storage, systems and scenes",
   "license": "Apache-2.0",
   "type": "module",
@@ -27,7 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "driftscript": "1.13.1"
+    "driftscript": "1.14.0"
   },
   "author": "Drift Technologies",
   "repository": {

package/src/index.ts

@@ -16,7 +16,12 @@
  * and a future inspector all read **one** description of a component, so there is no second one to
  * keep in sync.
  */
-export type { ComponentStoreOptions, ComponentType, StoreSnapshot } from './store.ts';
+export type {
+  ComponentDefault,
+  ComponentStoreOptions,
+  ComponentType,
+  StoreSnapshot,
+} from './store.ts';
 export { ComponentStore, createStoreSnapshot, defineComponent } from './store.ts';
 
 export type { ComponentView, ViewColumn } from './view.ts';

package/src/scene.ts

@@ -136,9 +136,11 @@ export function deserializeWorld(
       const instance: Record<string, unknown> = {};
       for (const field of from.fields) instance[field.name] = saved[field.id];
 
+      /* A field the file does not have takes the value the component declares for it, and zero or
+         nothing where it declares none. */
       const defaults: Record<string, unknown> = {};
       for (const field of type.schema.fields)
-        defaults[field.name] = field.type === 'String' ? null : 0;
+        defaults[field.name] = type.defaults[field.name] ?? (field.type === 'String' ? null : 0);
 
       const result = migrate(instance, from, type.schema, defaults);
       if (!result.migrated) return { loaded: false, reason: result.reason };

package/src/schedule.ts

@@ -116,7 +116,7 @@ function group(order: readonly SystemDefinition[]): (readonly SystemDefinition[]
   const groups: SystemDefinition[][] = [];
   let current: SystemDefinition[] = [];
   for (const system of order) {
-    if (current.length > 0 && current.some((other) => conflicts(other, system))) {
+    if (current.some((other) => conflicts(other, system))) {
       groups.push(current);
       current = [];
     }

package/src/store.ts

@@ -139,11 +139,27 @@ export interface ComponentType {
   readonly id: number;
   /** Fields typed `Entity`, which a scene load has to rewrite through its id map. */
   readonly entityFields: readonly string[];
+  /**
+   * The value each field was declared with, by field name; a field with none is absent and starts
+   * at zero, `false` or nothing.
+   *
+   * **Read wherever a field is not given**: an entity added with some of its fields, a prefab that
+   * names a few, a saved scene from before the field existed. A DriftScript component's come from
+   * the module's metadata (`seed: u32 = 7`); before they were read, every one of those paths
+   * filled zero and nothing said so.
+   */
+  readonly defaults: Readonly<Record<string, ComponentDefault>>;
 }
 
+/** A field's declared value: a number for every numeric and enum column, a flag, or a string. */
+export type ComponentDefault = number | string | boolean;
+
 let nextComponentId = 0;
 
-export function defineComponent(schema: Schema): ComponentType;
+export function defineComponent(
+  schema: Schema,
+  defaults?: Readonly<Record<string, ComponentDefault>>,
+): ComponentType;
 export function defineComponent(
   name: string,
   fields: Readonly<Record<string, string>>,
@@ -168,8 +184,16 @@ export function defineComponent(
  */
 export function defineComponent(
   first: Schema | string,
-  fields?: Readonly<Record<string, string>>,
+  second?: Readonly<Record<string, string>> | Readonly<Record<string, ComponentDefault>>,
 ): ComponentType {
+  const fields =
+    typeof first === 'string'
+      ? (second as Readonly<Record<string, string>> | undefined)
+      : undefined;
+  const defaults =
+    typeof first === 'string'
+      ? {}
+      : ((second as Readonly<Record<string, ComponentDefault>> | undefined) ?? {});
   const schema: Schema =
     typeof first === 'string'
       ? {
@@ -194,10 +218,31 @@ export function defineComponent(
     }
   }
 
+  /* A default names a field and fits its column, or the type is refused here, where a wrong one
+     is a fault in whoever declared it and not a value some later entity quietly starts with. */
+  for (const [name, value] of Object.entries(defaults)) {
+    const field = schema.fields.find((candidate) => candidate.name === name);
+    if (field === undefined) {
+      throw new Error(
+        `\`${schema.name}\` has a default for \`${name}\`, which is not one of its fields: ` +
+          `${schema.fields.map((f) => `\`${f.name}\``).join(', ')}.`,
+      );
+    }
+    const inner = optionInner(field.type) ?? field.type;
+    const wanted = inner === 'String' ? 'string' : inner === 'bool' ? 'boolean' : 'number';
+    if (typeof value !== wanted) {
+      throw new Error(
+        `\`${schema.name}.${name}\` is \`${field.type}\` and its default is the ${typeof value} ` +
+          `${JSON.stringify(value)}.`,
+      );
+    }
+  }
+
   return {
     name: schema.name,
     id: nextComponentId++,
     schema,
+    defaults: { ...defaults },
     /* An optional handle is still a handle, so a scene load has to rewrite it through the id map
        exactly as it rewrites a required one. Leaving it out would serialise a handle into a world
        whose indices mean something else. */
@@ -354,7 +399,9 @@ export class ComponentStore {
     for (const field of this.type.schema.fields) {
       const column = this.columns.get(field.name);
       if (column === undefined) continue;
-      const given = values[field.name];
+      /* Omitted takes the declared value; a `null` given for an optional field is its absence. */
+      const own = values[field.name];
+      const given = own === undefined ? this.type.defaults[field.name] : own;
       if (Array.isArray(column)) column[at] = given ?? null;
       else (column as NumericColumn)[at] = typeof given === 'number' ? given : Number(given ?? 0);
       /*