Adobe Data ECS Plugin Rules

PluginPropertyOrder [
  "extends — Plugin, base plugin to extend"
  "services — (db) => ServiceInstance, singleton service factories"
  "components — schema object, ECS component schemas"
  "resources — { default: value as Type }, global resource schemas"
  "archetypes — ['comp1', 'comp2'], standard ECS archetypes; storage tables for efficient insertions"
  "computed — (db) => Observe<T>, computed observables"
  "transactions — (store, payload) => void, synchronous deterministic atomic mutations"
  "actions — (db, payload) => T, general functions"
  "systems — { create: (db) => fn | void }, per-frame (60fps) or init-only"
]

Constraints {
  Properties must appear in this exact order; wrong order throws at runtime
}

export const authPlugin = Database.Plugin.create({
  extends: environmentPlugin,
  services: {
    auth: db => AuthService.createLazy({ services: db.services }),
  },
});

export const generationPlugin = Database.Plugin.create({
  extends: Database.Plugin.combine(aPlugin, bPlugin),
  computed: {
    max: db => Observe.withFilter(
        Observe.fromProperties({
            a: db.observe.resources.a,
            b: db.observe.resources.b
        }),
        ({ a, b }) => Math.max(a, b)
    )
  },
});

export const appPlugin = Database.Plugin.combine(
  corePlugin, themePlugin, dataPlugin,
  authPlugin, uiPlugin, featurePlugin
);

export type AppPlugin = typeof appPlugin;
export type AppDatabase = Database.Plugin.ToDatabase<AppPlugin>;

services: {
  environment: _db => EnvironmentService.create(),
}

components: {
  layout: Layout.schema,
  layoutElement: { default: null as unknown as HTMLElement, transient: true },
  layoutLayer: F32.schema,
},

resources: {
  themeColor: { default: 'dark' as ThemeColor },
  themeScale: { default: 'medium' as ThemeScale },
},

resources: {
  connection: { default: null as unknown as WebSocket },
},

archetypes: {
  Layout: ['layout', 'layoutElement', 'layoutLayer'],
},

computed: {
  max: db => Observe.withFilter(
    Observe.fromProperties({
      a: db.observe.resources.a,
      b: db.observe.resources.b,
    }),
    ({ a, b }) => Math.max(a, b)
  ),
},

transactions: {
  updateLayout: (store, { entity, layout }: { entity: Entity; layout: Layout }) => {
    store.update(entity, { layout });
  },
  setThemeColor: (store, color: ThemeColor) => {
    store.resources.themeColor = color;
  },
},

StoreAPI {
  "store.update(entity, data)" = "update entity components"
  "store.resources.x = value" = "mutate resources"
  "store.get(entity, 'component')" = "read component value"
  "store.read(entity)" = "read all entity component values"
  "store.read(entity, archetype)" = "read entity component values in archetype"
  "store.select(archetype.components, { where })" = "query entities"
}

actions: {
  generateNewName: async (db) => {
    const generatedName = await db.services.nameGenerator.generateName();
    db.transactions.setName(generatedName);
  },
  getAuth: db => db.services.auth,
},

systems: {
  ui_state_plugin_initialize: {
    create: db => {
      db.transactions.registerViews(views);
    },
  },
  layout_plugin__system: {
    create: db => {
      const observer = new ResizeObserver(/* ... */);
      Database.observeSelectDeep(db, db.archetypes.Layout.components)(entries => {
        // react to entity changes
      });
    },
  },
},

systems: {
  physics: {
    create: db => () => { /* per-tick work */ },
    schedule: {
      before: ['render'],
      after: ['input'],
      during: ['simulation'],
    },
  },
},

Schedule {
  before: "hard ordering constraints"
  after: "hard ordering constraints"
  during: "soft preference for same execution tier"
}

PluginNaming {
  file: "*-plugin.ts (kebab-case) — e.g. layout-plugin.ts"
  export: "*Plugin (camelCase) — e.g. layoutPlugin"
  system: "plugin_name__system (snake_case, double underscore) — e.g. layout_plugin__system"
  initSystem: "plugin_name_initialize — e.g. ui_state_plugin_initialize"
}

export type MyDatabase = Database.Plugin.ToDatabase<typeof myPlugin>;
export type MyStore = Database.Plugin.ToStore<typeof myPlugin>;

fn whenCreatingOrModifyingPlugin() {
  Constraints {
    Verify property order matches (extends, services, components, resources, archetypes, computed, transactions, actions, systems)
    Use extends for single-parent; Database.Plugin.combine() for multiple peers
    Ensure services only access db.services from extended plugins (not forward references)
    Export type *Database = Database.Plugin.ToDatabase<typeof *Plugin> when consumers need typed db access
    Follow naming conventions for files, exports, and systems
  }
}