dredless 1.0.1 → 1.1.1

package/docs/PROTOCOL.md

@@ -211,6 +211,11 @@ worldState.tileDefinition(material: number): TileDefinition | null;
 modelState.itemHolders(): ItemHolderSummary[];
 modelState.fabricators(): FabricatorSummary[];
 modelState.players(): PlayerSummary[];
+modelState.projectiles(): ProjectileSummary[];
+modelState.bots(): BotSummary[];
+modelState.rcds(): RcdSummary[];
+modelState.balls(): BallSummary[];
+modelState.recyclers(): RecyclerSummary[];
 modelState.setLocalPlayerEntity(entity: number | null): void;
 modelState.shipControls(): ShipControlSummary[];
 modelState.shipMetadata(): ShipWorldMetadataSummary | null;

package/docs/README.md

@@ -19,6 +19,7 @@ In a browser, `BrowserSession` uses the ambient browser cookie jar.
 | Handle disconnects and retain useful state                       | [Client lifecycle](CLIENT.md)                                                          |
 | Subscribe to model, inventory, or management updates             | [Event catalog](EVENTS.md)                                                             |
 | Find an entity, machine, or nearby ship                          | [World and entity reads](WORLD_STATE.md)                                               |
+| Read projectiles, bots, balls/eggs, RCDs, or recyclers           | [Special entity reads](WORLD_STATE.md#projectiles-bots-and-special-entities)             |
 | Move, aim, equip, or place a blueprint                           | [Player and inventory](PLAYER_INVENTORY.md)                                            |
 | Use a context menu or set door access                            | [Machines and context menus](MACHINES.md#context-menus-and-access)                     |
 | Configure a loader, pusher, launcher, or navigation unit         | [Machine reference](MACHINES.md)                                                       |

package/docs/WORLD_STATE.md

@@ -7,6 +7,7 @@
 - [Choose a world](#choose-a-world)
 - [Entities and features](#entities-and-features)
 - [Machine and other collections](#machine-and-other-collections)
+- [Projectiles, bots, and special entities](#projectiles-bots-and-special-entities)
 - [Nearby ships](#nearby-ships)
 - [Live reads and snapshots](#live-reads-and-snapshots)
 - [Coordinates and incomplete data](#coordinates-and-incomplete-data)
@@ -105,6 +106,76 @@ not freeze them.
 Materials summarize decoded blocks; they are not an authoritative ship inventory. A missing collection or component can
 reflect incomplete decoding, not an absent server object.
 
+## Projectiles, bots, and special entities
+
+Every world domain exposes these collections. They return current component summaries; `get()` returns `null` when
+the entity or requested component is absent. Use `world.entities.get(summary.entity)` for position, health, snapshots,
+and generic interactions.
+
+```ts
+world.projectiles.all(): ProjectileSummary[];
+world.projectiles.get(entity: EntityRef): ProjectileSummary | null;
+world.bots.all(): BotSummary[];
+world.bots.get(entity: EntityRef): BotSummary | null;
+world.rcds.all(): RcdSummary[];
+world.rcds.get(entity: EntityRef): RcdSummary | null;
+world.balls.all(): BallSummary[];
+world.balls.get(entity: EntityRef): BallSummary | null;
+world.recyclers.all(): RecyclerSummary[];
+world.recyclers.get(entity: EntityRef): RecyclerSummary | null;
+```
+
+These arrays also appear in world/model snapshots. Standalone models expose `projectiles()`, `bots()`, `rcds()`,
+`balls()`, and `recyclers()`. Entity handles recognize the `projectile`, `bot`, `rcd`, `ball`, and `recycler` features.
+An egg has public type `"egg"` and a `ball` component with `isEgg: true`; the balls collection includes both kinds.
+
+| Component | Exposed state |
+| --- | --- |
+| `projectile` | RGB `color`/`colorCss`, `botStyle`, `indicatorCount`, `spriteItemId`/`spriteItemName`, raw `state`. |
+| `bot` | Existing class/identifier fields, `classificationSource: "heuristic"`, health, nullable combat display state, and nullable `beams`. |
+| `rcd` | Sandbox/flux variant and variant code, corresponding item ID, stored item identity/count, beam vector, raw `state`. |
+| `ball` | Nullable `health`, radius in world units, `rubber`, `isEgg`, raw `state`. |
+| `recycler` | Stored item identity/count. Identified from the recycler marker in a ship interior. |
+
+Projectile `botStyle` selects the official bot-bullet sprite; it does not prove ownership or identify the shooter.
+`indicatorCount` is the number of orbiting visual markers. `spriteItemId` is the item image used by the official
+renderer when present, not a reliable identification of the ammunition or its damage. Projectile lifetimes follow
+normal entity updates/removals; no local projectile simulation or trajectory prediction is performed.
+
+`bot.combat` exposes packed RGBA `bodyColorRgba` and `weaponColorRgba`, `aimAngle` in radians, `thrusterMask`,
+`alternateSprite`, `beamEffectEnabled`, and raw combat `state`. The official disabled-angle sentinel becomes `null`.
+RGBA uses `0xRRGGBBAA`; projectile and outfit colors use RGB. Thruster mask bits select visual thrusters and do not
+provide thrust force. Beam enablement describes an effect, not whether a target is taking damage.
+
+`bot.beams` and the entity's `combatBeams` feature expose the same replicated three-beam component:
+`{entity, beams: [{angle, length, active, colorRgba}, ...], state}`. Angles are radians relative to the entity's
+orientation; lengths are in world units, and `active` means the length is positive. The renderer begins these beams
+at the object's radius, so `length` is the extension beyond that radius. Wire angles are divided by `1000`, lengths
+by `10`. The beam component is decoded separately from expando-box sizing.
+
+Bot class names remain inferred from component combinations and values, rather than an authoritative server type.
+Entities with health alone are no longer automatically treated as bots. Projectiles, balls, and RCDs are excluded
+from bot/crate inference. Server AI decisions, target identity, and weapon damage are not inferred from display fields.
+
+Ball identification uses the decoded ball component, including objects described in-game as boulders. It does not
+depend on a particular HP value or the previous boulder exclusion heuristic. Balls may have health, including rubber
+balls; `health` is `null` only when that component is absent. `radius` comes from the size component divided by `20`.
+`rubber` is `true` for rubber and `false` for rock. The official renderer tints rubber dark gray (`#222222`) and
+rock white. This flag is independent of health/destructibility.
+
+An RCD's `beam` is `{offsetX, offsetY, active}`. The vector uses world axes and world units, scaled from the wire by
+`1/5`; its endpoint is the RCD's position plus that vector. The official renderer chooses sandbox for variant code
+zero and flux otherwise. Stored items are reported without assuming that every item is valid fuel or assigning a
+fuel capacity. Generic `entity.use()`/tip interactions remain available; there is no dedicated RCD programming API.
+
+Recyclers expose the replicated held item without inventing a processing timer. Body/appearance-only entities and
+other special objects may still have generic handles and raw component tables without a dedicated summary. An
+annihilator is a block material in the official client, so it is represented through tiles rather than this collection.
+
+Footprints and the block index are coarse occupancy aids, not collision polygons or navigation meshes. Check
+`footprint.source`: `"default"` and `"heuristic"` dimensions are estimates, and hover outlines describe highlights.
+Helm/comms occupancy retains its existing inference rules; these collections do not establish player-to-machine links.
+
 ## Nearby ships
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "dredless",
-    "version": "1.0.1",
+    "version": "1.1.1",
     "description": "A fully-featured and from-scratch headless drednot.io client implementation written in pure js.",
     "license": "MIT",
     "homepage": "https://github.com/certainhuman/dredless#readme",

package/src/client/domains/index.js

@@ -427,6 +427,11 @@ export class WorldDomain {
         this.entities = new EntityCollection(client, scope);
         this.machines = new MachineCollection(client, scope);
         this.players = new PlayerCollection(client, scope);
+        this.projectiles = new EntitySummaryCollection(client, scope, "projectiles");
+        this.bots = new EntitySummaryCollection(client, scope, "bots");
+        this.rcds = new EntitySummaryCollection(client, scope, "rcds");
+        this.balls = new EntitySummaryCollection(client, scope, "balls");
+        this.recyclers = new EntitySummaryCollection(client, scope, "recyclers");
         this.blocks = new BlockCollection(client, scope);
         this.materials = new MaterialCollection(client, scope);
     }
@@ -569,6 +574,24 @@ export class PlayerCollection {
     }
 }
 
+class EntitySummaryCollection {
+    constructor(client, scope, method) {
+        this.client = client;
+        this.scope = scope;
+        this.method = method;
+        this.component = {projectiles: "projectile", bots: "bot", rcds: "rcd", balls: "ball", recyclers: "recycler"}[method];
+    }
+
+    all() {
+        return worldStateFor(this.client, this.scope)?.model[this.method]() || [];
+    }
+
+    get(entity) {
+        const id = entityIdOf(entity);
+        return worldStateFor(this.client, this.scope)?.model.entity(id)?.contents?.[this.component] || null;
+    }
+}
+
 export class BlockCollection {
     constructor(client, scope) {
         this.client = client;
@@ -1413,6 +1436,7 @@ export class ShipHandle {
 }
 
 const ENTITY_COMPONENT_ALIASES = new Map([
+    ["combatbeams", "combatBeams"],
     ["hoveroutline", "hoverOutline"],
     ["outline", "hoverOutline"],
     ["itemholder", "itemHolder"],
@@ -1465,6 +1489,12 @@ const MACHINE_COMPONENTS = [
 ];
 
 const ENTITY_FEATURES = [
+    "combatBeams",
+    "projectile",
+    "bot",
+    "rcd",
+    "ball",
+    "recycler",
     "health",
     "position",
     "outline",
@@ -1531,6 +1561,10 @@ function sourceWithProperty(contents, names, property) {
 }
 
 function entityPublicType(summary, contents) {
+    if (contents?.projectile) return "projectile";
+    if (contents?.rcd) return "rcd";
+    if (contents?.ball) return contents.ball.isEgg ? "egg" : "ball";
+    if (contents?.recycler) return "recycler";
     const machine = entityMachineType(contents);
     if (machine) return machine;
     if (contents?.player || summary?.category === "player") return "player";

package/src/index.d.ts

@@ -932,6 +932,11 @@ export interface WorldDomain {
     entities: EntityCollection;
     machines: MachineCollection;
     players: PlayerCollection;
+    projectiles: EntitySummaryCollection<ProjectileSummary>;
+    bots: EntitySummaryCollection<BotSummary>;
+    rcds: EntitySummaryCollection<RcdSummary>;
+    balls: EntitySummaryCollection<BallSummary>;
+    recyclers: EntitySummaryCollection<RecyclerSummary>;
     blocks: BlockCollection;
     materials: MaterialCollection;
 
@@ -976,6 +981,12 @@ export interface PlayerCollection {
     current(): PlayerSummary | null;
 }
 
+/** Current component summaries; get() returns null for a missing entity or component. */
+export interface EntitySummaryCollection<T> {
+    all(): T[];
+    get(entity: EntityRef): T | null;
+}
+
 export interface BlockCollection {
     all(): BlockSummary[];
 
@@ -1065,6 +1076,11 @@ export interface MachineCollection {
 }
 
 export type EntityPublicType =
+    | "projectile"
+    | "rcd"
+    | "ball"
+    | "egg"
+    | "recycler"
     | "loader"
     | "pusher"
     | "launcher"
@@ -1556,6 +1572,11 @@ export interface CargoEjectorSummary {
 }
 
 export interface EntityContentsSummary {
+    combatBeams?: CombatBeamsSummary;
+    projectile?: ProjectileSummary;
+    rcd?: RcdSummary;
+    ball?: BallSummary;
+    recycler?: RecyclerSummary;
     itemHolder?: ItemHolderSummary;
     expandoBox?: ExpandoBoxSummary;
     hoverOutline?: HoverOutlineSummary;
@@ -1591,7 +1612,7 @@ export interface EntityContentsSummary {
 
 export interface EntitySummary {
     entity: number;
-    category: "placed_entity" | "loose_item" | "untyped_holder" | "metadata" | "player" | "ship_control" | "blueprint_preview" | "entity";
+    category: "placed_entity" | "loose_item" | "untyped_holder" | "metadata" | "player" | "ship_control" | "blueprint_preview" | "projectile" | "ball" | "rcd" | "entity";
     typeId: number | null;
     typeName: string | null;
     markerTypeId: number | null;
@@ -1789,6 +1810,11 @@ export interface WorldSnapshot {
     transforms: TransformSummary[];
     machines: MachineSummary;
     players: PlayerSummary[];
+    projectiles: ProjectileSummary[];
+    bots: BotSummary[];
+    rcds: RcdSummary[];
+    balls: BallSummary[];
+    recyclers: RecyclerSummary[];
     shipControls: ShipControlSummary[];
     commsBubbles: CommsBubbleSummary[];
     tiles?: Tile[];
@@ -1883,6 +1909,12 @@ export class ModelState {
 
     players(): PlayerSummary[];
 
+    projectiles(): ProjectileSummary[];
+    bots(): BotSummary[];
+    rcds(): RcdSummary[];
+    balls(): BallSummary[];
+    recyclers(): RecyclerSummary[];
+
     shipControls(): ShipControlSummary[];
 
     shipMetadata(): ShipWorldMetadataSummary | null;
@@ -1904,6 +1936,11 @@ export interface ModelSnapshot {
     blocks?: BlockSummary[];
     transforms: TransformSummary[];
     players: PlayerSummary[];
+    projectiles: ProjectileSummary[];
+    bots: BotSummary[];
+    rcds: RcdSummary[];
+    balls: BallSummary[];
+    recyclers: RecyclerSummary[];
     shipControls: ShipControlSummary[];
     machines: MachineSummary;
     tables: unknown[];
@@ -2017,6 +2054,75 @@ export interface BotSummary {
     identifier: string;
     typeA: number | null;
     typeB: number | null;
+    classificationSource: "heuristic";
+    health: HealthSummary;
+    beams: CombatBeamsSummary | null;
+    combat: BotCombatSummary | null;
+}
+
+export interface CombatBeamsSummary {
+    entity: number;
+    /** Three replicated beams; angles are radians, lengths are world units. */
+    beams: { angle: number; length: number; active: boolean; colorRgba: number }[];
+    state: ModelRecord;
+}
+
+export interface BotCombatSummary {
+    /** Packed RGBA, unlike the RGB projectile and outfit colors. */
+    bodyColorRgba: number;
+    weaponColorRgba: number;
+    /** Radians; the official -7 sentinel becomes null. */
+    aimAngle: number | null;
+    thrusterMask: number;
+    alternateSprite: boolean;
+    beamEffectEnabled: boolean;
+    state: ModelRecord;
+}
+
+export interface ProjectileSummary {
+    entity: number;
+    /** Packed RGB trail/tint color. */
+    color: number;
+    colorCss: string;
+    /** Selects the official bot-bullet sprite; not an ownership guarantee. */
+    botStyle: boolean;
+    /** Count of orbiting visual markers. No inferred damage or ammo semantics. */
+    indicatorCount: number;
+    spriteItemId: number | null;
+    spriteItemName: string | null;
+    state: ModelRecord;
+}
+
+export interface BallSummary {
+    entity: number;
+    health: HealthSummary | null;
+    /** World units, when the size component is available. */
+    radius: number | null;
+    /** True for rubber, false for rock; independent of health/destructibility. */
+    rubber: boolean;
+    isEgg: boolean;
+    state: ModelRecord;
+}
+
+export interface RcdSummary {
+    entity: number;
+    variant: "sandbox" | "flux";
+    /** Official renderer selects sandbox for zero and flux otherwise. */
+    variantCode: number;
+    itemId: 121 | 122;
+    storedItemId: number | null;
+    storedItemName: string | null;
+    storedItemCount: number | null;
+    /** Vector from the RCD in world axes, in world units. */
+    beam: { offsetX: number; offsetY: number; active: boolean };
+    state: ModelRecord;
+}
+
+export interface RecyclerSummary {
+    entity: number;
+    storedItemId: number | null;
+    storedItemName: string | null;
+    storedItemCount: number | null;
 }
 
 export interface FabricatorSummary {

package/src/state/model/decoder.js

@@ -45,19 +45,13 @@ export const TWO_FIELD_SPEC = {
 
 export const LABEL_STATE_SPEC = {
     name: "label_state",
-    read(reader, record, mask) {
-        if (mask & 1) record.blob20 = reader.readBlob();
-        if (mask & 2) {
-            if (mask & 1) record.blob24 = reader.readBlob();
-            else record.q20 = (record.q20 || 0) + reader.readFieldDelta();
-        }
-        if (mask & 4) record.q28 = (record.q28 || 0) + reader.readFieldDelta();
-        if (mask & 8) {
-            if (mask & 1) record.q32 = (record.q32 || 0) + reader.readFieldDelta();
-            else record.blob28 = reader.readBlob();
-        }
-        if (mask & 16) record.q36 = (record.q36 || 0) + reader.readFieldDelta();
-    }
+    // Packed flag first, two independent text blobs,
+    // then two numeric deltas. Field types never depend on another mask bit.
+    // Keep the existing summary keys for the strings and colors.
+    packedBeforeValues: true,
+    packedBits: [{bit: 16, offset: 36}],
+    blobs: [{bit: 1, offset: 20}, {bit: 2, offset: 24}],
+    fields: numericFields({4: 28, 8: 32})
 };
 
 export const SIMPLE_LABEL_STATE_SPEC = {
@@ -141,6 +135,10 @@ export const MODEL_TABLE_SPECS = new Map([
     [11, {name: "numeric_sparse", fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32, 16: 36})}],
     [12, {name: "numeric_sparse", fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32})}],
     [14, {name: "size_state", fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32, 16: 36, 32: 40, 64: 44})}],
+    [15, {
+        name: "combat_beams",
+        fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32, 16: 36, 32: 40, 64: 44, 128: 48, 256: 52})
+    }],
     [16, {
         name: "label_numeric_state",
         read(reader, record, mask) {
@@ -158,29 +156,25 @@ export const MODEL_TABLE_SPECS = new Map([
             if (mask & 16) record.q36 = (record.q36 || 0) + reader.readFieldDelta();
         }
     }],
-    [17, {name: "numeric_sparse", fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32, 16: 36})}],
+    [17, {
+        name: "ball",
+        packedBeforeValues: true,
+        packedBits: [{bit: 1, offset: 21}, {bit: 2, offset: 22}]
+    }],
     [18, {
         name: "mob_combat_state",
+        // Official reader packs flags 64/2048 before numeric deltas. Raw offsets
+        // follow that reader's layout, rather than treating flag bits as values.
+        packedBeforeValues: true,
+        packedBits: [{bit: 64, offset: 77}, {bit: 2048, offset: 78}],
+        defaults: {
+            q20: -1, q24: 0, q28: 0, q32: 0, q36: 0, q40: -9417217,
+            q44: 0, q48: -100, q52: 0, q56: 10, q60: 10, q64: 1, q68: 1, q72: 100
+        },
         fields: numericFields({
-            2: 20,
-            4: 24,
-            8: 28,
-            16: 32,
-            32: 36,
-            64: 40,
-            128: 44,
-            256: 48,
-            512: 52,
-            1024: 56,
-            2048: 60,
-            4096: 64,
-            8192: 68,
-            16384: 72,
-            32768: 76,
-            65536: 80,
-            131072: 84,
-            524288: 88,
-            4194304: 92
+            2: 20, 4: 24, 8: 28, 16: 32, 32: 36, 128: 40,
+            256: 44, 512: 48, 1024: 52, 4096: 56, 8192: 60,
+            16384: 64, 32768: 68, 65536: 72
         })
     }],
     [19, {name: "motion_state", packedBits: [{bit: 4, offset: 29}], ...TWO_FIELD_SPEC}],
@@ -214,7 +208,13 @@ export const MODEL_TABLE_SPECS = new Map([
         fields: numericFields({1: 20, 2: 24}),
         blobs: [{bit: 4, offset: 28}, {bit: 8, offset: 40}]
     }],
-    [24, {name: "projectile_state", packedBits: [{bit: 8, offset: 33}], fields: numericFields({1: 20, 2: 24, 4: 28})}],
+    [24, {
+        name: "projectile_state",
+        defaults: {q20: 16777215, q24: 1, q28: 1},
+        packedBeforeValues: true,
+        packedBits: [{bit: 2, offset: 33}],
+        fields: numericFields({1: 20, 4: 24, 8: 28})
+    }],
     [25, {
         name: "zone_label",
         orderedValues: true,
@@ -279,7 +279,7 @@ export const MODEL_TABLE_SPECS = new Map([
         defaults: {q20: 0, q24: 0, q28: 0, q32: 0, q36: 0, q40: 0, q44: 0, q48: 0, q52: 0, q56: 0, q60: 0, q64: 0},
         fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32, 16: 36, 32: 40, 64: 44, 128: 48, 256: 52, 512: 56, 1024: 60, 2048: 64})
     }],
-    [59, {name: "numeric_sparse", fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32, 16: 36})}],
+    [59, {name: "rcd", fields: numericFields({1: 20, 2: 24, 4: 28, 8: 32})}],
     [60, {name: "fluid_tank", packedBits: [{bit: 4, offset: 29}], ...TWO_FIELD_SPEC}],
     [61, {name: "shield_charge", ...TWO_FIELD_SPEC}],
     [62, {name: "flag_state", packedBits: [{bit: 1, offset: 21}], fields: []}],
@@ -358,7 +358,7 @@ export const WIRE_TAG_TABLES = new Map([
     [48, 12],
     [49, 13],
     [50, 14],
-    [51, 51],
+    [51, 15],
     [52, 16],
     [74, 17],
     [80, 17],
@@ -790,45 +790,120 @@ export function summarizeBot(entity, {
     combatRecord,
     motionRecord,
     table10Record,
-    table51Record,
+    beamRecord,
     itemCrate,
     player,
     shipControl
 }) {
-    if (!health || itemCrate || player || shipControl || isBoulderBotExclusion(health, table2Record, combatRecord)) return null;
+    if (!health || itemCrate || player || shipControl) return null;
     const className = botClassFromState({
         health,
         table2Record,
         smallRecord,
         combatRecord,
         table10Record,
-        table51Record
+        beamRecord
     });
+    // Health alone is not enough to identify an arbitrary entity as a bot.
+    if (className === "bot") return null;
     return {
         entity,
         className,
+        classificationSource: "heuristic",
+        health,
+        beams: summarizeCombatBeams(entity, beamRecord),
+        combat: combatRecord ? {
+            bodyColorRgba: (combatRecord.q20 ?? -1) >>> 0,
+            weaponColorRgba: (combatRecord.q40 ?? -9417217) >>> 0,
+            aimAngle: combatRecord.q44 === -70 ? null : numberOrNull(combatRecord.q44, 10),
+            thrusterMask: combatRecord.q60 ?? 10,
+            alternateSprite: Boolean(combatRecord.q77),
+            beamEffectEnabled: Boolean(combatRecord.q78),
+            state: cloneRecord(combatRecord)
+        } : null,
         identifier: botIdentifierFromState({combatRecord, motionRecord, smallRecord}),
         typeA: health.state?.q28 ?? null,
         typeB: health.state?.q32 ?? null
     };
 }
 
-export function isBoulderBotExclusion(health, table2Record, combatRecord) {
-    return Boolean(
-        health?.maxHp === 2000 &&
-        health?.state?.q28 === 30 &&
-        health?.state?.q32 != null &&
-        table2Record?.q20 != null &&
-        table2Record?.q24 == null &&
-        !combatRecord
-    );
+export function summarizeProjectile(entity, record) {
+    if (!record) return null;
+    const color = record.q20 ?? 16777215;
+    const itemId = record.q28 ?? 1;
+    return {
+        entity,
+        color,
+        colorCss: colorToCss(color),
+        botStyle: Boolean(record.q33),
+        indicatorCount: record.q24 ?? 1,
+        spriteItemId: itemId === 0 ? null : itemId,
+        spriteItemName: itemId === 0 ? null : entityNameFromType(itemId),
+        state: cloneRecord(record)
+    };
+}
+
+export function summarizeCombatBeams(entity, record) {
+    if (!record) return null;
+    return {
+        entity,
+        beams: [0, 1, 2].map((index) => {
+            const length = (record[qKey(32 + index * 4)] ?? 0) / 10;
+            return {
+                angle: (record[qKey(20 + index * 4)] ?? 0) / 1000,
+                length,
+                active: length > 0,
+                colorRgba: (record[qKey(44 + index * 4)] ?? 0) >>> 0
+            };
+        }),
+        state: cloneRecord(record)
+    };
+}
+
+export function summarizeBall(entity, record, health = null, sizeRecord = null) {
+    if (!record) return null;
+    return {
+        entity,
+        health,
+        radius: numberOrNull(sizeRecord?.q20, 20),
+        rubber: Boolean(record.q21),
+        isEgg: Boolean(record.q22),
+        state: cloneRecord(record)
+    };
+}
+
+export function summarizeRcd(entity, record, itemHolderRecord) {
+    if (!record) return null;
+    const variant = (record.q20 ?? 0) === 0 ? "sandbox" : "flux";
+    const item = itemSummary(itemHolderRecord?.q20, itemHolderRecord?.q24);
+    return {
+        entity,
+        variant,
+        variantCode: record.q20 ?? 0,
+        itemId: variant === "sandbox" ? 121 : 122,
+        storedItemId: item.itemId,
+        storedItemName: item.itemName,
+        storedItemCount: item.count,
+        beam: {
+            offsetX: (record.q28 ?? 0) / 5,
+            offsetY: (record.q32 ?? 0) / 5,
+            active: Boolean(record.q28 || record.q32)
+        },
+        state: cloneRecord(record)
+    };
+}
+
+export function summarizeRecycler(entity, marker, itemHolderRecord) {
+    if (!marker) return null;
+    const item = itemSummary(itemHolderRecord?.q20, itemHolderRecord?.q24);
+    return {entity, storedItemId: item.itemId, storedItemName: item.itemName, storedItemCount: item.count};
 }
 
-export function botClassFromState({health, table2Record, smallRecord, combatRecord, table10Record, table51Record}) {
+export function botClassFromState({health, table2Record, smallRecord, combatRecord, table10Record, beamRecord}) {
     if (isYellowMineGuardBotState({health, smallRecord, combatRecord, table2Record})) return "yellow-mine-guard";
     if (isShieldHelperBotState({health, table2Record})) return "shield-helper";
     if (isShieldMasterBotState({health, table2Record})) return "shield-master";
-    if (isLazerEnthusiastBotState({health, table2Record, table10Record, table51Record})) return "lazer-enthusiast";
+    if (isLazerEnthusiastBotState({health, table2Record, table10Record, beamRecord})) return "lazer-enthusiast";
     if (isCowardBossState({health})) return "the-coward";
     if (isOrangeFoolBotState({combatRecord})) return "orange-fool";
     if (isZombieBossBotState({health, table2Record, combatRecord})) return "zombie-boss";
@@ -842,6 +917,7 @@ export function botClassFromState({health, table2Record, smallRecord, combatReco
     if (isAquaShielderBotState({health, table2Record, combatRecord})) return "aqua-shielder";
     if (table2Record) return "table2-bot";
     if (combatRecord) return "combat-bot";
+    if (beamRecord) return "beam-bot";
     return "bot";
 }
 
@@ -895,14 +971,14 @@ export function isAquaShielderBotState({health, table2Record, combatRecord}) {
     );
 }
 
-export function isLazerEnthusiastBotState({health, table2Record, table10Record, table51Record}) {
+export function isLazerEnthusiastBotState({health, table2Record, table10Record, beamRecord}) {
     return (
         health?.state?.q28 === 140 &&
         health?.state?.q32 === 155 &&
         table2Record?.q20 === 300 &&
         table2Record?.q24 === -900 &&
         Boolean(table10Record) &&
-        Boolean(table51Record)
+        Boolean(beamRecord)
     );
 }
 
@@ -1515,6 +1591,10 @@ export function entityFootprint(entity) {
 }
 
 export function entityLabel(entity) {
+    if (entity?.projectile) return "Projectile";
+    if (entity?.ball) return entity.ball.isEgg ? "Egg" : "Ball";
+    if (entity?.rcd) return entity.rcd.variant === "sandbox" ? "Sandbox RCD" : "Flux RCD";
+    if (entity?.recycler) return "Recycler";
     if (entity?.category === "metadata" && entity?.typeName) return `Metadata ${entity.typeName}`;
     if (entity?.blueprintPreview) return `Blueprint Preview (${entity.blueprintPreview.itemName ?? entity.blueprintPreview.itemId ?? "item"})`;
     if (entity?.category === "loose_item" && entity?.itemHolder?.itemName) return `Loose ${entity.itemHolder.itemName}`;
@@ -1546,6 +1626,10 @@ export function entityLabel(entity) {
 }
 
 export function entityCategory(entity) {
+    if (entity?.projectile) return "projectile";
+    if (entity?.ball) return "ball";
+    if (entity?.rcd) return "rcd";
+    if (entity?.recycler) return "placed_entity";
     if (entity?.player) return "player";
     if (entity?.blueprintPreview) return "blueprint_preview";
     if (entity?.shipControl) return "ship_control";

package/src/state/model/index.d.ts

@@ -2,6 +2,13 @@ export {
     FabricatorType,
     ModelState,
     decodeModelData,
+    type ProjectileSummary,
+    type BotCombatSummary,
+    type CombatBeamsSummary,
+    type BotSummary,
+    type RcdSummary,
+    type BallSummary,
+    type RecyclerSummary,
     type ModelRecord,
     type ModelSnapshot,
     type EntitySummary,