@underpostnet/cyberia 3.3.73 → 3.3.77

package/src/client/components/cyberia/EntityEngineCyberia.js

@@ -1,14 +1,15 @@
 import { BtnIcon } from '../core/BtnIcon.js';
-import { Input } from '../core/Input.js';
 import { commonModeratorGuard } from '../core/CommonJs.js';
 import { htmls, s } from '../core/VanillaJs.js';
 import { NotificationManager } from '../core/NotificationManager.js';
 import { Translate } from '../core/Translate.js';
-import { darkTheme, dynamicCol, ThemeEvents } from '../core/Css.js';
+import { darkTheme, ThemeEvents } from '../core/Css.js';
 import { DropDown } from '../core/DropDown.js';
 import { AgGrid } from '../core/AgGrid.js';
+import { getProxyPath } from '../core/Router.js';
 import { ObjectLayerService } from '../../services/object-layer/object-layer.service.js';
 import { CyberiaEntityTypeDefaultService } from '../../services/cyberia-entity-type-default/cyberia-entity-type-default.service.js';
+import { CyberiaInstanceConfService } from '../../services/cyberia-instance-conf/cyberia-instance-conf.service.js';
 import { ENTITY_TYPES, SELECTABLE_ENTITY_BEHAVIORS } from './SharedDefaultsCyberia.js';
 
 // DropDown invokes optionData.onClick on selection, so every option must carry one.
@@ -19,8 +20,8 @@ const subtleBorder = () => (darkTheme ? '#444' : '#e0e0e0');
 // EntityEngineCyberia — CRUD surface for the cyberia-entity-type-default
 // collection (the DB-backed mirror of ENTITY_TYPE_DEFAULTS). An ag-grid lists
 // every default; clicking a row loads it into the form. The form binds an
-// entityType to its lifecycle item-id sets (live / dead / drop) plus the seed
-// defaultObjectLayers, with server-backed item-id autocomplete pickers so the
+// entityType to its lifecycle item-id sets (live / dead / drop) plus the
+// inventory-only extras, with server-backed item-id autocomplete pickers so the
 // high-frequency itemId fields stay fast and typo-free. The runtime linking
 // rule (entity matches entityType AND carries an active itemId from liveItemIds)
 // is content-authority only; this engine never mutates entities or the
@@ -33,7 +34,17 @@ class EntityEngineCyberia {
   static liveItemIds = [];
   static deadItemIds = [];
   static dropItemIds = [];
-  static defaultObjectLayers = [];
+  static inventoryItemsIds = [];
+  // Per-id overrides of what the lists derive: { itemId, active, quantity }.
+  static overrideItemsIdsState = [];
+  // Instance codes whose conf references the loaded default, and every code that could.
+  static instanceCodes = [];
+  static availableInstanceCodes = [];
+  // entityDefault _id → instance codes, for the grid column. Built with the list.
+  static instanceLinks = new Map();
+  // itemId → item type. A sprite lives under its type, so an item id alone cannot be previewed.
+  // Types never change, so this is a cache that only ever grows: ids reach it from the list and
+  // from every id added in the form, which is what makes a just-picked item preview immediately.
 
   static gridId = 'entity-engine-grid';
 
@@ -43,7 +54,9 @@ class EntityEngineCyberia {
     liveItemPicker: 'entity-engine-live-item-picker',
     deadItemPicker: 'entity-engine-dead-item-picker',
     dropItemPicker: 'entity-engine-drop-item-picker',
-    layerItemPicker: 'entity-engine-layer-item-picker',
+    inventoryItemPicker: 'entity-engine-inventory-item-picker',
+    instancePicker: 'entity-engine-instance-picker',
+    overrideItemPicker: 'entity-engine-override-item-picker',
   };
 
   // Behavior options: a leading "auto" (empty → runtime derives armed→hostile,
@@ -84,20 +97,51 @@ class EntityEngineCyberia {
       containerClass: 'inl',
       serviceProvider: async (q) => {
         const result = await ObjectLayerService.searchItemIds({ q });
-        if (result.status === 'success' && result.data?.itemIds) {
-          return result.data.itemIds.map((itemId) => dropdownOption(itemId));
+        if (result.status === 'success' && result.data?.items) {
+          return result.data.items.map(({ id }) => dropdownOption(id));
         }
         return [];
       },
     });
   }
 
-  // ── Item-id list editors (live / dead / drop) ────────────────────────────
+  // Instance codes are a small, already-loaded set, so the picker filters them in place rather
+  // than round-tripping per keystroke the way the item-id pickers do.
+  static async buildInstanceDropdown(id) {
+    return await DropDown.instance({
+      id,
+      label: html`Search instance code`,
+      data: [],
+      containerClass: 'inl',
+      serviceProvider: async (q) => {
+        const query = String(q || '').toLowerCase();
+        return EntityEngineCyberia.availableInstanceCodes
+          .filter((code) => !query || code.toLowerCase().includes(query))
+          .map((code) => dropdownOption(code));
+      },
+    });
+  }
+
+  // ── Item-id list editors ─────────────────────────────────────────────────
+  // The lifecycle discriminators plus the inventory-only extras. All four are plain id lists:
+  // what an entity carries is their union, and what is active follows from the list, never from
+  // a flag stored per row. Form field → stored key, so nothing that holds item ids can be left
+  // out of the type resolution or the grid.
+  static ITEM_FIELD_KEYS = Object.freeze({
+    live: 'liveItemIds',
+    dead: 'deadItemIds',
+    drop: 'dropItemIds',
+    inventory: 'inventoryItemsIds',
+  });
+
+  static ITEM_FIELDS = Object.keys(EntityEngineCyberia.ITEM_FIELD_KEYS);
+
   static listFieldOf(field) {
     return {
       live: EntityEngineCyberia.liveItemIds,
       dead: EntityEngineCyberia.deadItemIds,
       drop: EntityEngineCyberia.dropItemIds,
+      inventory: EntityEngineCyberia.inventoryItemsIds,
     }[field];
   }
 
@@ -111,7 +155,9 @@ class EntityEngineCyberia {
         class="fl"
         style="border-bottom:1px solid ${subtleBorder()};padding:3px 0;align-items:center;font-size:12px;font-family:monospace;"
       >
-        <div class="in fll" style="flex:1;">${items[i]}</div>
+        <div class="in fll" style="flex:1;display:flex;align-items:center;gap:6px;">
+          ${EntityEngineCyberia.itemPreview(items[i])}${items[i]}
+        </div>
         ${await BtnIcon.instance({
           class: `btn-entity-engine-rm-${field}-${i}`,
           label: html`<i class="fa-solid fa-xmark"></i>`,
@@ -130,7 +176,7 @@ class EntityEngineCyberia {
     }
   }
 
-  static addItem(field, pickerId) {
+  static async addItem(field, pickerId) {
     const itemId = EntityEngineCyberia.getSingleDropdownValue(pickerId);
     if (!itemId) {
       NotificationManager.Push({ html: 'Select an itemId first.', status: 'error' });
@@ -143,83 +189,342 @@ class EntityEngineCyberia {
     }
     list.push(itemId);
     EntityEngineCyberia.setSingleDropdownValue(pickerId, '');
-    EntityEngineCyberia.renderItemList(field);
+    await EntityEngineCyberia.renderItemList(field);
+  }
+
+  // ── Override rules ({ itemId, active, quantity }) ─────────────────────────
+  // Every id the four lists carry, which is exactly what an override may adjust.
+  static carriedItemIds() {
+    return [
+      ...new Set(
+        EntityEngineCyberia.ITEM_FIELDS.flatMap((field) => EntityEngineCyberia.listFieldOf(field)).filter(Boolean),
+      ),
+    ];
   }
 
-  // ── Default object-layer rows ({ itemId, active, quantity }) ──────────────
-  static async renderLayerList() {
-    const container = s('.entity-engine-layer-list');
+  static async renderOverrideList() {
+    const container = s('.entity-engine-override-list');
     if (!container) return;
+    const carried = new Set(EntityEngineCyberia.carriedItemIds());
     let out = '';
-    for (let i = 0; i < EntityEngineCyberia.defaultObjectLayers.length; i++) {
-      const l = EntityEngineCyberia.defaultObjectLayers[i];
+    for (let i = 0; i < EntityEngineCyberia.overrideItemsIdsState.length; i++) {
+      const rule = EntityEngineCyberia.overrideItemsIdsState[i];
+      // An override for an id no list carries is inert — the union decides membership.
+      const orphan = !carried.has(rule.itemId);
+      // Drop chance only reaches the simulation for an id the drop list carries, so the input is
+      // offered where it can do something and the reason is stated where it cannot.
+      const isDrop = EntityEngineCyberia.listFieldOf('drop').includes(rule.itemId);
       out += html`<div
         class="fl"
         style="border-bottom:1px solid ${subtleBorder()};padding:3px 0;align-items:center;font-size:12px;font-family:monospace;"
       >
-        <div class="in fll" style="flex:1;">
-          ${l.itemId}
-          <span style="color:${l.active ? (darkTheme ? '#7ec77e' : '#2a7d2a') : '#888'};">
-            · ${l.active ? 'active' : 'inactive'}</span
-          >
-          · ×${l.quantity}
+        <div class="in fll" style="flex:1;display:flex;align-items:center;gap:6px;">
+          ${EntityEngineCyberia.itemPreview(rule.itemId)}
+          <span style="${orphan ? 'color:#c90;' : ''}">${rule.itemId}</span>
+          <label style="cursor:pointer;display:inline-flex;align-items:center;gap:4px;">
+            <input class="entity-engine-override-active-${i}" type="checkbox" ${rule.active ? 'checked' : ''} />
+            active
+          </label>
+          <span>×</span>
+          <input
+            class="entity-engine-override-qty-${i}"
+            type="number"
+            min="1"
+            value="${rule.quantity}"
+            style="width:60px;"
+          />
+          ${isDrop
+            ? html`<label
+                style="cursor:pointer;display:inline-flex;align-items:center;gap:4px;"
+                title="Probability this id scatters on death. 1 always drops, 0 never does."
+              >
+                drop
+                <input
+                  class="entity-engine-override-drop-chance-${i}"
+                  type="number"
+                  min="0"
+                  max="1"
+                  step="0.05"
+                  value="${Number.isFinite(rule.dropChance) ? rule.dropChance : 1}"
+                  style="width:60px;"
+                />
+              </label>`
+            : ''}
+          ${orphan ? html`<span style="color:#c90;font-size:11px;">no list carries this id</span>` : ''}
         </div>
         ${await BtnIcon.instance({
-          class: `btn-entity-engine-rm-layer-${i}`,
+          class: `btn-entity-engine-rm-override-${i}`,
           label: html`<i class="fa-solid fa-xmark"></i>`,
           style: 'min-width:30px;padding:2px 8px;',
         })}
       </div>`;
     }
-    if (!out) out = '<div style="color:#888;font-size:12px;">No default object layers.</div>';
-    htmls('.entity-engine-layer-list', out);
-    for (let i = 0; i < EntityEngineCyberia.defaultObjectLayers.length; i++) {
-      if (s(`.btn-entity-engine-rm-layer-${i}`))
-        s(`.btn-entity-engine-rm-layer-${i}`).onclick = () => {
-          EntityEngineCyberia.defaultObjectLayers.splice(i, 1);
-          EntityEngineCyberia.renderLayerList();
+    if (!out) out = '<div style="color:#888;font-size:12px;">No overrides — every id starts as its list derives.</div>';
+    htmls('.entity-engine-override-list', out);
+    for (let i = 0; i < EntityEngineCyberia.overrideItemsIdsState.length; i++) {
+      const active = s(`.entity-engine-override-active-${i}`);
+      if (active) active.onchange = () => (EntityEngineCyberia.overrideItemsIdsState[i].active = active.checked);
+      const qty = s(`.entity-engine-override-qty-${i}`);
+      if (qty)
+        qty.onchange = () =>
+          (EntityEngineCyberia.overrideItemsIdsState[i].quantity = Math.max(1, parseInt(qty.value) || 1));
+      const dropChance = s(`.entity-engine-override-drop-chance-${i}`);
+      if (dropChance)
+        dropChance.onchange = () => {
+          const parsed = parseFloat(dropChance.value);
+          const rule = EntityEngineCyberia.overrideItemsIdsState[i];
+          // An empty or unreadable box means "say nothing", which the whole pipeline reads as
+          // always drops — the same as a world that never set one.
+          if (!Number.isFinite(parsed)) delete rule.dropChance;
+          else rule.dropChance = Math.min(1, Math.max(0, parsed));
+          dropChance.value = Number.isFinite(rule.dropChance) ? rule.dropChance : 1;
+        };
+      if (s(`.btn-entity-engine-rm-override-${i}`))
+        s(`.btn-entity-engine-rm-override-${i}`).onclick = () => {
+          EntityEngineCyberia.overrideItemsIdsState.splice(i, 1);
+          EntityEngineCyberia.renderOverrideList();
         };
     }
   }
 
-  static addLayer() {
-    const itemId = EntityEngineCyberia.getSingleDropdownValue(EntityEngineCyberia.ids.layerItemPicker);
+  static async addOverride() {
+    const itemId = EntityEngineCyberia.getSingleDropdownValue(EntityEngineCyberia.ids.overrideItemPicker);
     if (!itemId) {
-      NotificationManager.Push({ html: 'Select an itemId for the object layer.', status: 'error' });
+      NotificationManager.Push({ html: 'Select an itemId to override.', status: 'error' });
+      return;
+    }
+    if (EntityEngineCyberia.overrideItemsIdsState.some((rule) => rule.itemId === itemId)) {
+      NotificationManager.Push({ html: `"${itemId}" already has an override.`, status: 'warning' });
+      return;
+    }
+    EntityEngineCyberia.overrideItemsIdsState.push({
+      itemId,
+      active: EntityEngineCyberia.listFieldOf('live').includes(itemId),
+      quantity: 1,
+    });
+    EntityEngineCyberia.setSingleDropdownValue(EntityEngineCyberia.ids.overrideItemPicker, '');
+    await EntityEngineCyberia.renderOverrideList();
+  }
+
+  // ── Instance links (CyberiaInstanceConf.entityDefaults) ───────────────────
+  static async renderInstanceList() {
+    const container = s('.entity-engine-instance-list');
+    if (!container) return;
+    let out = '';
+    for (let i = 0; i < EntityEngineCyberia.instanceCodes.length; i++) {
+      out += html`<div
+        class="fl"
+        style="border-bottom:1px solid ${subtleBorder()};padding:3px 0;align-items:center;font-size:12px;font-family:monospace;"
+      >
+        <div class="in fll" style="flex:1;">${EntityEngineCyberia.instanceCodes[i]}</div>
+        ${await BtnIcon.instance({
+          class: `btn-entity-engine-rm-instance-${i}`,
+          label: html`<i class="fa-solid fa-xmark"></i>`,
+          style: 'min-width:30px;padding:2px 8px;',
+        })}
+      </div>`;
+    }
+    if (!out) {
+      out = html`<div style="color:#888;font-size:12px;">
+        No instance runs on this default — it reaches no world until one references it.
+      </div>`;
+    }
+    htmls('.entity-engine-instance-list', out);
+    for (let i = 0; i < EntityEngineCyberia.instanceCodes.length; i++) {
+      if (s(`.btn-entity-engine-rm-instance-${i}`))
+        s(`.btn-entity-engine-rm-instance-${i}`).onclick = () => {
+          EntityEngineCyberia.instanceCodes.splice(i, 1);
+          EntityEngineCyberia.renderInstanceList();
+        };
+    }
+  }
+
+  static addInstance() {
+    const code = EntityEngineCyberia.getSingleDropdownValue(EntityEngineCyberia.ids.instancePicker);
+    if (!code) {
+      NotificationManager.Push({ html: 'Select an instance code first.', status: 'error' });
       return;
     }
-    if (EntityEngineCyberia.defaultObjectLayers.some((l) => l.itemId === itemId)) {
-      NotificationManager.Push({ html: `Object layer "${itemId}" already added.`, status: 'warning' });
+    if (EntityEngineCyberia.instanceCodes.includes(code)) {
+      NotificationManager.Push({ html: `"${code}" already linked.`, status: 'warning' });
       return;
     }
-    const active = !!s('.entity-engine-layer-active')?.checked;
-    const quantity = Math.max(0, parseInt(s('.entity-engine-layer-qty')?.value) || 0);
-    EntityEngineCyberia.defaultObjectLayers.push({ itemId, active, quantity });
-    EntityEngineCyberia.setSingleDropdownValue(EntityEngineCyberia.ids.layerItemPicker, '');
-    if (s('.entity-engine-layer-active')) s('.entity-engine-layer-active').checked = false;
-    if (s('.entity-engine-layer-qty')) s('.entity-engine-layer-qty').value = 0;
-    EntityEngineCyberia.renderLayerList();
+    EntityEngineCyberia.instanceCodes.push(code);
+    EntityEngineCyberia.setSingleDropdownValue(EntityEngineCyberia.ids.instancePicker, '');
+    EntityEngineCyberia.renderInstanceList();
+  }
+
+  // Persisted after the default itself: an instance can only reference a document that exists.
+  static async persistInstanceLinks() {
+    if (!EntityEngineCyberia.currentId) return;
+    const result = await CyberiaEntityTypeDefaultService.setInstances({
+      id: EntityEngineCyberia.currentId,
+      body: { instanceCodes: EntityEngineCyberia.instanceCodes },
+    });
+    if (result.status === 'error') {
+      NotificationManager.Push({ html: result.message, status: 'error' });
+      return;
+    }
+    const { linked = [], unlinked = [] } = result.data || {};
+    if (linked.length || unlinked.length) {
+      NotificationManager.Push({
+        html: `Instances updated${linked.length ? ` · linked ${linked.join(', ')}` : ''}${
+          unlinked.length ? ` · unlinked ${unlinked.join(', ')}` : ''
+        }`,
+        status: 'success',
+      });
+    }
   }
 
   // ── Grid (CRUD list surface) ──────────────────────────────────────────────
+  static ITEM_PREVIEW_PX = 60;
+
+  // The item's first idle frame, or the placeholder when its type is unresolved or the art is
+  // missing. Both absences look the same on purpose: either way the runtime cannot draw it.
+  static itemPreview(itemId) {
+    const size = EntityEngineCyberia.ITEM_PREVIEW_PX;
+    const placeholder = (display) =>
+      html`<div style="width:${size}px;height:${size}px;display:${display};align-items:center;justify-content:center;">
+        <i class="fas fa-image" style="font-size:${Math.round(size / 2)}px;color:#999;"></i>
+      </div>`;
+    return html`<img
+        src="${getProxyPath()}api/atlas-sprite-sheet/idle-preview/${itemId}"
+        style="width:${size}px;height:${size}px;display:block;image-rendering:pixelated;"
+        alt="${itemId}"
+        onerror="this.style.display='none';this.nextElementSibling.style.display='flex';"
+      />
+      ${placeholder('none')}`;
+  }
+
+  // Item ids read as a strip of sprites, each labelled with its id: a default is recognised by
+  // what it looks like long before anyone reads the ids. Arrays stay arrays on the row so the
+  // renderer can lay them out; ag-grid's text filter still sees the comma-joined form.
+  static itemIdsRenderer(field) {
+    return class {
+      eGui;
+
+      init(params) {
+        this.eGui = document.createElement('div');
+        const itemIds = params.data?.[field] || [];
+        if (itemIds.length === 0) {
+          this.eGui.innerHTML = html`<span style="color:#666;font-style:italic;">—</span>`;
+          return;
+        }
+        this.eGui.style.cssText = 'display:flex;flex-wrap:wrap;align-items:center;gap:6px;padding:4px 0;';
+        this.eGui.innerHTML = itemIds
+          .map(
+            (itemId, index) =>
+              html`<span
+                style="display:inline-flex;align-items:center;gap:4px;font-size:11px;font-family:monospace;"
+                title="${itemId}"
+                >${EntityEngineCyberia.itemPreview(itemId)}${itemId}${index < itemIds.length - 1 ? ',' : ''}</span
+              >`,
+          )
+          .join('');
+      }
+
+      getGui() {
+        return this.eGui;
+      }
+
+      refresh() {
+        return true;
+      }
+    };
+  }
+
+  // The overrides a default carries, one rule per line. No sprite here: a rule is read as a rule —
+  // whether the id is active, how many of it, and which id it adjusts — and the id's own strip is
+  // already three columns to the left.
+  static overridesRenderer() {
+    return class {
+      eGui;
+
+      init(params) {
+        this.eGui = document.createElement('div');
+        const rules = params.data?.overrideItemsIdsState || [];
+        if (rules.length === 0) {
+          this.eGui.innerHTML = html`<span style="color:#666;font-style:italic;">—</span>`;
+          return;
+        }
+        this.eGui.style.cssText = 'display:flex;flex-direction:column;gap:2px;padding:4px 0;';
+        this.eGui.innerHTML = rules
+          .map(
+            ({ itemId, active, quantity, dropChance }) =>
+              html`<span
+                style="font-size:11px;font-family:monospace;white-space:nowrap;${active ? '' : 'color:#888;'}"
+                title="${itemId}"
+                >${active ? 'active' : 'inactive'} ×${Math.max(1, quantity || 1)}${Number.isFinite(dropChance) &&
+                1 !== dropChance
+                  ? ` drop ${dropChance}`
+                  : ''} ${itemId}</span
+              >`,
+          )
+          .join('');
+      }
+
+      getGui() {
+        return this.eGui;
+      }
+
+      refresh() {
+        return true;
+      }
+    };
+  }
+
+  // What the grid's text filter reads for a column of rules, since an array of objects has no
+  // useful string form of its own.
+  static overridesFilterText = (rules = []) =>
+    rules
+      .map(
+        ({ itemId, active, quantity, dropChance }) =>
+          `${itemId} ${active ? 'active' : 'inactive'} x${quantity || 1}` +
+          (Number.isFinite(dropChance) && 1 !== dropChance ? ` drop${dropChance}` : ''),
+      )
+      .join(', ');
+
   static toRow(doc) {
     return {
       _id: doc._id,
       entityType: doc.entityType || '',
       behavior: doc.behavior || '',
-      liveItemIds: (doc.liveItemIds || []).join(', '),
-      deadItemIds: (doc.deadItemIds || []).join(', '),
-      dropItemIds: (doc.dropItemIds || []).join(', '),
-      objectLayers: (doc.defaultObjectLayers || []).length,
+      instances: (EntityEngineCyberia.instanceLinks.get(String(doc._id)) || []).join(', '),
+      liveItemIds: [...(doc.liveItemIds || [])],
+      deadItemIds: [...(doc.deadItemIds || [])],
+      dropItemIds: [...(doc.dropItemIds || [])],
+      inventoryItemsIds: [...(doc.inventoryItemsIds || [])],
+      overrideItemsIdsState: [...(doc.overrideItemsIdsState || [])],
     };
   }
 
+  // The link lives on CyberiaInstanceConf.entityDefaults, so one conf read answers it for every
+  // row at once — there is no second place to ask, and nothing to keep in sync.
+  static async refreshInstanceLinks() {
+    const res = await CyberiaInstanceConfService.get({ limit: 500 });
+    const confs = res?.data?.data || [];
+    EntityEngineCyberia.availableInstanceCodes = confs.map((conf) => conf.instanceCode).sort();
+    EntityEngineCyberia.instanceLinks = new Map();
+    for (const conf of confs) {
+      for (const ref of conf.entityDefaults || []) {
+        const key = String(ref);
+        if (!EntityEngineCyberia.instanceLinks.has(key)) EntityEngineCyberia.instanceLinks.set(key, []);
+        EntityEngineCyberia.instanceLinks.get(key).push(conf.instanceCode);
+      }
+    }
+    for (const codes of EntityEngineCyberia.instanceLinks.values()) codes.sort();
+  }
+
   static async refreshList() {
-    const res = await CyberiaEntityTypeDefaultService.get({ limit: 500 });
+    const [res] = await Promise.all([
+      CyberiaEntityTypeDefaultService.get({ limit: 500 }),
+      EntityEngineCyberia.refreshInstanceLinks(),
+    ]);
     EntityEngineCyberia.listCache = res?.data?.data || [];
     const rows = EntityEngineCyberia.listCache.map((d) => EntityEngineCyberia.toRow(d));
     if (AgGrid.grids[EntityEngineCyberia.gridId])
       AgGrid.grids[EntityEngineCyberia.gridId].setGridOption('rowData', rows);
+    EntityEngineCyberia.renderInstanceList();
   }
 
   static notifyResult(result, isUpdate) {
@@ -242,10 +547,14 @@ class EntityEngineCyberia {
       liveItemIds: [...EntityEngineCyberia.liveItemIds],
       deadItemIds: [...EntityEngineCyberia.deadItemIds],
       dropItemIds: [...EntityEngineCyberia.dropItemIds],
-      defaultObjectLayers: EntityEngineCyberia.defaultObjectLayers.map((l) => ({
-        itemId: l.itemId,
-        active: !!l.active,
-        quantity: l.quantity || 0,
+      inventoryItemsIds: [...EntityEngineCyberia.inventoryItemsIds],
+      overrideItemsIdsState: EntityEngineCyberia.overrideItemsIdsState.map((rule) => ({
+        itemId: rule.itemId,
+        active: !!rule.active,
+        quantity: Math.max(1, rule.quantity || 1),
+        // Sent only when authored. Omitting it is what makes the id drop every time, so a rule
+        // that never touched the input reads the same as every rule written before it existed.
+        ...(Number.isFinite(rule.dropChance) ? { dropChance: rule.dropChance } : {}),
       })),
     };
   }
@@ -257,15 +566,17 @@ class EntityEngineCyberia {
     EntityEngineCyberia.liveItemIds = [...(doc.liveItemIds || [])];
     EntityEngineCyberia.deadItemIds = [...(doc.deadItemIds || [])];
     EntityEngineCyberia.dropItemIds = [...(doc.dropItemIds || [])];
-    EntityEngineCyberia.defaultObjectLayers = (doc.defaultObjectLayers || []).map((l) => ({
-      itemId: l.itemId,
-      active: !!l.active,
-      quantity: l.quantity || 0,
+    EntityEngineCyberia.inventoryItemsIds = [...(doc.inventoryItemsIds || [])];
+    EntityEngineCyberia.overrideItemsIdsState = (doc.overrideItemsIdsState || []).map((rule) => ({
+      itemId: rule.itemId,
+      active: !!rule.active,
+      quantity: Math.max(1, rule.quantity || 1),
+      ...(Number.isFinite(rule.dropChance) ? { dropChance: rule.dropChance } : {}),
     }));
-    EntityEngineCyberia.renderItemList('live');
-    EntityEngineCyberia.renderItemList('dead');
-    EntityEngineCyberia.renderItemList('drop');
-    EntityEngineCyberia.renderLayerList();
+    EntityEngineCyberia.instanceCodes = [...(EntityEngineCyberia.instanceLinks.get(String(doc._id)) || [])];
+    for (const field of EntityEngineCyberia.ITEM_FIELDS) EntityEngineCyberia.renderItemList(field);
+    EntityEngineCyberia.renderOverrideList();
+    EntityEngineCyberia.renderInstanceList();
     NotificationManager.Push({ html: `Entity default "${doc.entityType}" loaded`, status: 'success' });
   }
 
@@ -274,13 +585,14 @@ class EntityEngineCyberia {
     EntityEngineCyberia.liveItemIds = [];
     EntityEngineCyberia.deadItemIds = [];
     EntityEngineCyberia.dropItemIds = [];
-    EntityEngineCyberia.defaultObjectLayers = [];
+    EntityEngineCyberia.inventoryItemsIds = [];
+    EntityEngineCyberia.overrideItemsIdsState = [];
+    EntityEngineCyberia.instanceCodes = [];
     EntityEngineCyberia.setSingleDropdownValue(EntityEngineCyberia.ids.entityType, '');
     EntityEngineCyberia.setSingleDropdownValue(EntityEngineCyberia.ids.behavior, '');
-    EntityEngineCyberia.renderItemList('live');
-    EntityEngineCyberia.renderItemList('dead');
-    EntityEngineCyberia.renderItemList('drop');
-    EntityEngineCyberia.renderLayerList();
+    for (const field of EntityEngineCyberia.ITEM_FIELDS) EntityEngineCyberia.renderItemList(field);
+    EntityEngineCyberia.renderOverrideList();
+    EntityEngineCyberia.renderInstanceList();
   }
 
   static validate(body) {
@@ -310,6 +622,7 @@ class EntityEngineCyberia {
     EntityEngineCyberia.notifyResult(result, isUpdate);
     if (result.status === 'success') {
       if (result.data?._id) EntityEngineCyberia.currentId = result.data._id;
+      await EntityEngineCyberia.persistInstanceLinks();
       await EntityEngineCyberia.refreshList();
     }
   }
@@ -324,7 +637,10 @@ class EntityEngineCyberia {
     if (!EntityEngineCyberia.validate(body)) return;
     const result = await CyberiaEntityTypeDefaultService.put({ id: EntityEngineCyberia.currentId, body });
     EntityEngineCyberia.notifyResult(result, true);
-    if (result.status === 'success') await EntityEngineCyberia.refreshList();
+    if (result.status === 'success') {
+      await EntityEngineCyberia.persistInstanceLinks();
+      await EntityEngineCyberia.refreshList();
+    }
   }
 
   // Clone: create a NEW document from the current form values (POST), then load
@@ -338,6 +654,7 @@ class EntityEngineCyberia {
     EntityEngineCyberia.notifyResult(result, false);
     if (result.status === 'success') {
       if (result.data?._id) EntityEngineCyberia.currentId = result.data._id;
+      await EntityEngineCyberia.persistInstanceLinks();
       await EntityEngineCyberia.refreshList();
       NotificationManager.Push({ html: 'Cloned into a new entity default.', status: 'success' });
     }
@@ -370,12 +687,12 @@ class EntityEngineCyberia {
     EntityEngineCyberia.liveItemIds = [];
     EntityEngineCyberia.deadItemIds = [];
     EntityEngineCyberia.dropItemIds = [];
-    EntityEngineCyberia.defaultObjectLayers = [];
+    EntityEngineCyberia.inventoryItemsIds = [];
+    EntityEngineCyberia.overrideItemsIdsState = [];
+    EntityEngineCyberia.instanceCodes = [];
 
     const ids = EntityEngineCyberia.ids;
     const entityTypeOptions = Object.values(ENTITY_TYPES).map((t) => dropdownOption(t));
-    const cont = 'entity-engine-container';
-    const dc = { layer: 'entity-engine-dc-layer' };
 
     const group = (title, icon, inner) =>
       html`<div class="in" style="border:1px solid ${groupBorder()};border-radius:8px;padding:12px;margin-bottom:14px;">
@@ -405,19 +722,19 @@ class EntityEngineCyberia {
 
     setTimeout(async () => {
       ThemeEvents['entity-engine-theme'] = () => {
-        EntityEngineCyberia.renderItemList('live');
-        EntityEngineCyberia.renderItemList('dead');
-        EntityEngineCyberia.renderItemList('drop');
-        EntityEngineCyberia.renderLayerList();
+        for (const field of EntityEngineCyberia.ITEM_FIELDS) EntityEngineCyberia.renderItemList(field);
+        EntityEngineCyberia.renderOverrideList();
       };
 
-      for (const field of ['live', 'dead', 'drop'])
+      for (const field of EntityEngineCyberia.ITEM_FIELDS)
         if (s(`.btn-entity-engine-add-${field}`))
           s(`.btn-entity-engine-add-${field}`).onclick = () =>
             EntityEngineCyberia.addItem(field, ids[`${field}ItemPicker`]);
 
-      if (s('.btn-entity-engine-add-layer'))
-        s('.btn-entity-engine-add-layer').onclick = () => EntityEngineCyberia.addLayer();
+      if (s('.btn-entity-engine-add-override'))
+        s('.btn-entity-engine-add-override').onclick = () => EntityEngineCyberia.addOverride();
+      if (s('.btn-entity-engine-add-instance'))
+        s('.btn-entity-engine-add-instance').onclick = () => EntityEngineCyberia.addInstance();
       if (s('.btn-entity-engine-save')) s('.btn-entity-engine-save').onclick = () => EntityEngineCyberia.save();
       if (s('.btn-entity-engine-update')) s('.btn-entity-engine-update').onclick = () => EntityEngineCyberia.update();
       if (s('.btn-entity-engine-clone')) s('.btn-entity-engine-clone').onclick = () => EntityEngineCyberia.clone();
@@ -426,10 +743,8 @@ class EntityEngineCyberia {
       if (s('.btn-entity-engine-refresh'))
         s('.btn-entity-engine-refresh').onclick = () => EntityEngineCyberia.refreshList();
 
-      EntityEngineCyberia.renderItemList('live');
-      EntityEngineCyberia.renderItemList('dead');
-      EntityEngineCyberia.renderItemList('drop');
-      EntityEngineCyberia.renderLayerList();
+      for (const field of EntityEngineCyberia.ITEM_FIELDS) EntityEngineCyberia.renderItemList(field);
+      EntityEngineCyberia.renderOverrideList();
       await EntityEngineCyberia.refreshList();
     });
 
@@ -457,10 +772,44 @@ class EntityEngineCyberia {
               columnDefs: [
                 { field: 'entityType', headerName: 'Entity Type', minWidth: 120 },
                 { field: 'behavior', headerName: 'Behavior', minWidth: 110 },
-                { field: 'liveItemIds', headerName: 'Live Item Ids' },
-                { field: 'deadItemIds', headerName: 'Dead Item Ids' },
-                { field: 'dropItemIds', headerName: 'Drop Item Ids' },
-                { field: 'objectLayers', headerName: 'OL', minWidth: 70 },
+                { field: 'instances', headerName: 'Instances', minWidth: 160 },
+                {
+                  field: 'liveItemIds',
+                  headerName: 'Live Item Ids',
+                  minWidth: 220,
+                  autoHeight: true,
+                  cellRenderer: EntityEngineCyberia.itemIdsRenderer('liveItemIds'),
+                },
+                {
+                  field: 'deadItemIds',
+                  headerName: 'Dead Item Ids',
+                  minWidth: 220,
+                  autoHeight: true,
+                  cellRenderer: EntityEngineCyberia.itemIdsRenderer('deadItemIds'),
+                },
+                {
+                  field: 'dropItemIds',
+                  headerName: 'Drop Item Ids',
+                  minWidth: 220,
+                  autoHeight: true,
+                  cellRenderer: EntityEngineCyberia.itemIdsRenderer('dropItemIds'),
+                },
+                {
+                  field: 'inventoryItemsIds',
+                  headerName: 'Inventory Items Id',
+                  minWidth: 220,
+                  autoHeight: true,
+                  cellRenderer: EntityEngineCyberia.itemIdsRenderer('inventoryItemsIds'),
+                },
+                {
+                  field: 'overrideItemsIdsState',
+                  headerName: 'Resume Override',
+                  minWidth: 200,
+                  autoHeight: true,
+                  cellRenderer: EntityEngineCyberia.overridesRenderer(),
+                  filterValueGetter: (params) =>
+                    EntityEngineCyberia.overridesFilterText(params.data?.overrideItemsIdsState),
+                },
               ],
               rowSelection: 'single',
               onRowClicked: (event) => {
@@ -509,67 +858,89 @@ class EntityEngineCyberia {
       ${group('Dead Item Ids', 'fa-solid fa-skull', await itemListEditor('dead', html`Search dead itemId`))}
       ${group('Drop Item Ids', 'fa-solid fa-gift', await itemListEditor('drop', html`Search drop itemId`))}
       ${group(
-        'Default Object Layers',
-        'fa-solid fa-layer-group',
-        html`${dynamicCol({ containerSelector: cont, id: dc.layer, type: 'a-50-b-50' })}
+        'Inventory Items Id',
+        'fa-solid fa-box-open',
+        html`<div class="in" style="font-size:12px;color:#888;margin-bottom:8px;">
+            <i class="fa-solid fa-circle-info"></i> The entity carries the union of all four lists. These are the extras
+            no lifecycle state activates — a coin balance, say; live, dead and drop ids are already carried and are
+            activated by context.
+          </div>
+          ${await itemListEditor('inventory', html`Search inventory itemId`)}`,
+      )}
+      ${group(
+        'Override Item State',
+        'fa-solid fa-sliders',
+        html`<div class="in" style="font-size:12px;color:#888;margin-bottom:8px;">
+            <i class="fa-solid fa-circle-info"></i> Adjusts what the lists above derive for one id they already carry:
+            <b>active</b> forces the spawn state — a skin the equipment rules would otherwise leave inactive — and the
+            quantity sizes a stack, which is how a drop bundle declares how many it scatters. An override never adds an
+            id.
+          </div>
           <div class="fl" style="align-items:flex-end;">
-            <div class="in fll ${dc.layer}-col-a" style="padding-right:4px;">
-              ${await EntityEngineCyberia.buildItemIdDropdown(ids.layerItemPicker, html`Search itemId`)}
+            <div class="in fll" style="flex:1;">
+              ${await EntityEngineCyberia.buildItemIdDropdown(ids.overrideItemPicker, html`Search carried itemId`)}
             </div>
-            <div class="in fll ${dc.layer}-col-b" style="padding-left:4px;">
-              ${await Input.instance({
-                id: 'entity-engine-layer-qty',
-                label: html`Quantity`,
-                containerClass: 'inl',
-                type: 'number',
-                min: 0,
-                value: 0,
+            <div class="in fll" style="padding-left:6px;">
+              ${await BtnIcon.instance({
+                class: 'wfa btn-entity-engine-add-override',
+                label: html`<i class="fa-solid fa-plus"></i> Override`,
               })}
             </div>
           </div>
-          <div class="in" style="margin-top:8px;">
-            <label style="font-size:13px;cursor:pointer;">
-              <input class="entity-engine-layer-active" type="checkbox" /> Active on spawn
-            </label>
+          <div class="in entity-engine-override-list" style="margin-top:8px;"></div>`,
+      )}
+      ${group(
+        'Instances',
+        'fa-solid fa-earth-americas',
+        html`<div class="in" style="font-size:12px;opacity:.8;margin-bottom:8px;">
+            A world runs on this default only while its conf references it, and the reference is what scopes it — an
+            instance never picks up another's wiring by sharing item ids.
           </div>
-          <div class="in" style="margin-top:8px;">
-            ${await BtnIcon.instance({
-              class: 'wfa btn-entity-engine-add-layer',
-              label: html`<i class="fa-solid fa-plus"></i> Add Object Layer`,
-            })}
+          <div class="fl" style="align-items:flex-end;">
+            <div class="in fll" style="flex:1;">
+              ${await EntityEngineCyberia.buildInstanceDropdown(ids.instancePicker)}
+            </div>
+            <div class="in fll" style="padding-left:6px;">
+              ${await BtnIcon.instance({
+                class: 'wfa btn-entity-engine-add-instance',
+                label: html`<i class="fa-solid fa-plus"></i> Link`,
+              })}
+            </div>
           </div>
-          <div class="in entity-engine-layer-list" style="margin-top:8px;"></div>`,
+          <div class="in entity-engine-instance-list" style="margin-top:8px;"></div>`,
       )}
       ${group(
         'Save Entity Default',
         'fa-solid fa-floppy-disk',
         html`<div class="fl" style="margin-top:4px;flex-wrap:wrap;">
-          ${EntityEngineCyberia.canMutate
-            ? html`<div class="in fll" style="flex:1 1 120px;padding:3px;">
-                  ${await BtnIcon.instance({
+          ${
+            EntityEngineCyberia.canMutate
+              ? html`<div class="in fll" style="flex:1 1 120px;padding:3px;">
+                    ${await BtnIcon.instance({
                     class: 'wfa btn-entity-engine-save',
                     label: html`<i class="fa-solid fa-floppy-disk"></i> Save`,
                   })}
-                </div>
-                <div class="in fll" style="flex:1 1 120px;padding:3px;">
-                  ${await BtnIcon.instance({
+                  </div>
+                  <div class="in fll" style="flex:1 1 120px;padding:3px;">
+                    ${await BtnIcon.instance({
                     class: 'wfa btn-entity-engine-update',
                     label: html`<i class="fa-solid fa-pen-to-square"></i> Update`,
                   })}
-                </div>
-                <div class="in fll" style="flex:1 1 120px;padding:3px;">
-                  ${await BtnIcon.instance({
+                  </div>
+                  <div class="in fll" style="flex:1 1 120px;padding:3px;">
+                    ${await BtnIcon.instance({
                     class: 'wfa btn-entity-engine-clone',
                     label: html`<i class="fa-solid fa-clone"></i> Clone`,
                   })}
-                </div>
-                <div class="in fll" style="flex:1 1 120px;padding:3px;">
-                  ${await BtnIcon.instance({
+                  </div>
+                  <div class="in fll" style="flex:1 1 120px;padding:3px;">
+                    ${await BtnIcon.instance({
                     class: 'wfa btn-entity-engine-delete',
                     label: html`<i class="fa-solid fa-trash"></i> Delete`,
                   })}
-                </div>`
-            : ''}
+                  </div>`
+              : ''
+          }
           <div class="in fll" style="flex:1 1 120px;padding:3px;">
             ${await BtnIcon.instance({
               class: 'wfa btn-entity-engine-new',