Keep behavior variables private to their own graph (#257)

A behavior often needs working state such as a timer or a counter.
Until now every variable showed up on each placed object and in the
Properties menu, so the inspector filled up with values nobody should
touch. A private variable works like any other inside its graph but
is not offered anywhere outside.

- Each behavior variable gets a lock switch next to Keep. It starts
  off, so existing projects stay as they are (`privateVariables`).
- A placed object shows no private variable, neither in the
  inspector nor while the game runs. If all are private, it says so.
- Switching a variable to private drops its overrides on every
  placed object in one undo step. Switching back does not restore
  them.
- A running game does not write a private value back as an
  override, and a project change during the run does not reset it.
- `+ Property` no longer offers private variables. A port that
  names one by hand still reads and writes it without a warning.
- The default value of a private variable is read-only in the asset
  inspector. Its shape (name, fields, type, delete) stays editable.
- Keep is now a pin icon instead of a word. With the lock added, the
  header of a list variable had no room left and the lock covered
  `+ Item`.

Not done: the animation track picker still offers private variables.

Tests: ./check.sh -> 186 files, 2711 tests, CHECK EXIT 0.
e2e 1,19,20,21,56 -> ALL PASSED, 119 checks. New module 56 has
7 checks with a real mouse. Counter-checks fail as expected: unit
without the write-back filter, the sync guard, dropping overrides or
loading the flag. Browser with all variables on the object, an
unfiltered menu, or no value lock.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/core/commands/variableCommands.ts

@@ -5,7 +5,13 @@ import {
   type PropertyValue,
   type StructValue,
 } from '../model/Properties';
-import { isKeptVariable, setKeptVariable, type VariableOwnerAsset } from '../model/Asset';
+import {
+  isKeptVariable,
+  isPrivateVariable,
+  setKeptVariable,
+  setPrivateVariable,
+  type VariableOwnerAsset,
+} from '../model/Asset';
 import { overrideSites } from '../model/instance';
 import type { Project } from '../model/Project';
 import type { VariableKind } from '../properties/kinds';
@@ -93,7 +99,12 @@ function restoreOverrides(
 /** Removes a variable together with its default and every instance override. */
 export class RemoveVariableCommand implements Command {
   readonly label: string;
-  private removed?: { def: Removed<PropertyDef>; value: PropertyValue | undefined; kept: boolean };
+  private removed?: {
+    def: Removed<PropertyDef>;
+    value: PropertyValue | undefined;
+    kept: boolean;
+    hidden: boolean;
+  };
   private overrides: TakenOverride[] = [];
 
   constructor(
@@ -108,9 +119,13 @@ export class RemoveVariableCommand implements Command {
     const def = removeFirst(asset.variables, (v) => v.key === this.key);
     if (!def) throw new CommandError(`Variable "${this.key}" not found`);
     const kept = asset.type === 'behavior' && isKeptVariable(asset, this.key);
-    this.removed = { def, value: asset.props[this.key], kept };
+    const hidden = isPrivateVariable(asset, this.key);
+    this.removed = { def, value: asset.props[this.key], kept, hidden };
     delete asset.props[this.key];
-    if (asset.type === 'behavior') setKeptVariable(asset, this.key, false);
+    if (asset.type === 'behavior') {
+      setKeptVariable(asset, this.key, false);
+      setPrivateVariable(asset, this.key, false);
+    }
     this.overrides = takeOverrides(project, this.assetId, this.key);
   }
 
@@ -119,7 +134,10 @@ export class RemoveVariableCommand implements Command {
     const asset = requireVariableOwner(project, this.assetId);
     restoreAt(asset.variables, [this.removed.def]);
     if (this.removed.value !== undefined) asset.props[this.key] = this.removed.value;
-    if (this.removed.kept && asset.type === 'behavior') setKeptVariable(asset, this.key, true);
+    if (asset.type === 'behavior') {
+      if (this.removed.kept) setKeptVariable(asset, this.key, true);
+      if (this.removed.hidden) setPrivateVariable(asset, this.key, true);
+    }
     restoreOverrides(project, this.assetId, this.key, this.overrides);
   }
 }
@@ -143,9 +161,12 @@ export class RenameVariableCommand extends RenameCommand {
     if (asset.variables.some((v) => v.key === to)) throw new CommandError(`Variable "${to}" already exists`);
     def.key = to;
     def.label = to;
-    // Renamed in place, so the switch keeps its spot in the list.
-    if (asset.type === 'behavior' && asset.keptVariables)
-      asset.keptVariables = asset.keptVariables.map((k) => (k === from ? to : k));
+    // Renamed in place, so the switches keep their spot in the list.
+    if (asset.type === 'behavior') {
+      if (asset.keptVariables) asset.keptVariables = asset.keptVariables.map((k) => (k === from ? to : k));
+      if (asset.privateVariables)
+        asset.privateVariables = asset.privateVariables.map((k) => (k === from ? to : k));
+    }
     if (asset.props[from] !== undefined) {
       asset.props[to] = asset.props[from]!;
       delete asset.props[from];
@@ -185,6 +206,38 @@ export class SetVariableKeptCommand implements Command {
   }
 }
 
+/**
+ * Whether a behavior's variable is seen outside its own graph (#257). Going private drops the
+ * overrides of every placed object: nobody would see them any more, yet they would still act.
+ */
+export class SetVariablePrivateCommand implements Command {
+  readonly label: string;
+  private previous = false;
+  private overrides: TakenOverride[] = [];
+
+  constructor(
+    private readonly assetId: string,
+    private readonly key: string,
+    private readonly hidden: boolean,
+  ) {
+    this.label = hidden ? `Make ${key} private` : `Make ${key} public`;
+  }
+
+  execute(project: Project): void {
+    const asset = requireBehavior(project, this.assetId);
+    if (!asset.variables.some((v) => v.key === this.key))
+      throw new CommandError(`Variable "${this.key}" not found`);
+    this.previous = isPrivateVariable(asset, this.key);
+    setPrivateVariable(asset, this.key, this.hidden);
+    this.overrides = this.hidden ? takeOverrides(project, this.assetId, this.key) : [];
+  }
+
+  undo(project: Project): void {
+    setPrivateVariable(requireBehavior(project, this.assetId), this.key, this.previous);
+    restoreOverrides(project, this.assetId, this.key, this.overrides);
+  }
+}
+
 /**
  * A struct's fields are no properties of anything placed, so the reserved property names are free
  * there – as they are for a struct field.

src/core/model/Asset.ts

@@ -37,14 +37,20 @@ export interface SceneAsset extends AssetBase {
  * `keptVariables` names the variables a `Run behavior` call hands on to the next call from the same
  * node on the same object (#229); the others start at their default every call. Absent keeps none,
  * so a project from before the switch runs as it did, and a new variable starts out not kept.
+ *
+ * `privateVariables` names the variables only the behavior's own graph sees (#257): a placed object
+ * neither shows nor overrides them, and a `Properties` node does not offer them. Absent is none.
  */
 export interface BehaviorAsset extends AssetBase {
   type: 'behavior';
   variables: PropertyDef[];
   keptVariables?: string[];
+  privateVariables?: string[];
   graph: Graph;
 }
 
+type VariableSwitch = 'keptVariables' | 'privateVariables';
+
 /** Whether a call of this behavior hands `key` on to the next call (#229). */
 export function isKeptVariable(asset: BehaviorAsset, key: string): boolean {
   return asset.keptVariables?.includes(key) === true;
@@ -52,10 +58,28 @@ export function isKeptVariable(asset: BehaviorAsset, key: string): boolean {
 
 /** Writes the switch for one variable; an empty list is dropped rather than stored. */
 export function setKeptVariable(asset: BehaviorAsset, key: string, on: boolean): void {
-  const rest = (asset.keptVariables ?? []).filter((k) => k !== key);
+  setSwitch(asset, 'keptVariables', key, on);
+}
+
+/** Whether `key` is hidden from everything outside the behavior's own graph (#257). */
+export function isPrivateVariable(asset: Asset, key: string): boolean {
+  return asset.type === 'behavior' && asset.privateVariables?.includes(key) === true;
+}
+
+export function setPrivateVariable(asset: BehaviorAsset, key: string, on: boolean): void {
+  setSwitch(asset, 'privateVariables', key, on);
+}
+
+/** The variables a placed object shows and overrides: all but the private ones. */
+export function publicVariables(asset: BehaviorAsset): PropertyDef[] {
+  return asset.variables.filter((def) => !isPrivateVariable(asset, def.key));
+}
+
+function setSwitch(asset: BehaviorAsset, list: VariableSwitch, key: string, on: boolean): void {
+  const rest = (asset[list] ?? []).filter((k) => k !== key);
   const next = on ? [...rest, key] : rest;
-  if (next.length > 0) asset.keptVariables = next;
-  else delete asset.keptVariables;
+  if (next.length > 0) asset[list] = next;
+  else delete asset[list];
 }
 
 /**

src/core/store/serialize.ts

@@ -184,9 +184,14 @@ export function deserializeProject(raw: unknown, fallbackId = ''): Project {
         graph: normalizeGraph(a.graph),
       };
       // Only names that are declared, each once, in declaration order.
-      const kept = new Set(Array.isArray(a.keptVariables) ? a.keptVariables : []);
-      const keptVariables = declared.map((v) => v.key).filter((key) => kept.has(key));
+      const declaredOf = (list: unknown): string[] => {
+        const named = new Set(Array.isArray(list) ? list : []);
+        return declared.map((v) => v.key).filter((key) => named.has(key));
+      };
+      const keptVariables = declaredOf(a.keptVariables);
       if (keptVariables.length > 0) behavior.keptVariables = keptVariables;
+      const privateVariables = declaredOf(a.privateVariables);
+      if (privateVariables.length > 0) behavior.privateVariables = privateVariables;
       assets.push(behavior);
     } else if (type === 'variables') {
       const shared: VariablesAsset = { id, type, name, props, variables: variables.get(id) ?? [] };

src/editor/inspector/assetSection.ts

@@ -17,11 +17,13 @@ import {
   RenameStructFieldCommand,
   RenameVariableCommand,
   SetVariableKeptCommand,
+  SetVariablePrivateCommand,
 } from '../../core/commands/variableCommands';
 import type { Command } from '../../core/commands/Command';
 import {
   type Asset,
   isKeptVariable,
+  isPrivateVariable,
   isVariableOwner,
   type StateMachineAsset,
   type VariableOwnerAsset,
@@ -76,8 +78,12 @@ export function assetSignature(project: Project, assetId: string): string {
   // The same for the switch that keeps shared values between runs and for the scope beside it: the
   // notes, the button and whether the switch is shown at all depend on the two.
   const kept = asset.type === 'variables' ? `|${isPersistent(asset)}|${sharedScopeOf(asset)}` : '';
-  // A behavior's Keep buttons are drawn once per build and read their switch from it (#229).
-  const keeps = asset.type === 'behavior' ? `|keep:${[...(asset.keptVariables ?? [])].sort().join(',')}` : '';
+  // A behavior's Keep and Private buttons are drawn once per build and read their switch from it.
+  const keeps =
+    asset.type === 'behavior'
+      ? `|keep:${[...(asset.keptVariables ?? [])].sort().join(',')}` +
+        `|private:${[...(asset.privateVariables ?? [])].sort().join(',')}`
+      : '';
   // Vector art shows its shapes under its rows (#129), so a shape added or renamed is a new structure.
   const shapes = asset.type === 'vectorart' ? `|${shapeListSignature(asset)}` : '';
   const values = resolveAssetProps(project, asset);
@@ -273,18 +279,24 @@ export function buildVariables(host: InspectorHost, asset: VariableOwnerAsset, i
           ),
         ),
     };
-    const keep =
-      asset.type === 'behavior'
-        ? {
-            on: isKeptVariable(asset, def.key),
-            set: (on: boolean) => run(new SetVariableKeptCommand(asset.id, def.key, on)),
-          }
-        : undefined;
+    const behavior = asset.type === 'behavior';
+    const keep = behavior
+      ? {
+          on: isKeptVariable(asset, def.key),
+          set: (on: boolean) => run(new SetVariableKeptCommand(asset.id, def.key, on)),
+        }
+      : undefined;
+    const hidden = behavior
+      ? {
+          on: isPrivateVariable(asset, def.key),
+          set: (on: boolean) => run(new SetVariablePrivateCommand(asset.id, def.key, on)),
+        }
+      : undefined;
     const value = values[def.key] ?? def.default;
     const typing = structTyping(host, asset, def.key);
     host.fields.set(
       def.key,
-      buildVariable(host, def, value, assetHandlers(host, asset.id, def), { edit, typing, keep }),
+      buildVariable(host, def, value, assetHandlers(host, asset.id, def), { edit, typing, keep, hidden }),
     );
   }
 }

src/editor/inspector/objectSection.ts

@@ -17,7 +17,7 @@ import {
   SetEditorOffsetCommand,
   SetOverrideCommand,
 } from '../../core/commands/sceneObjectCommands';
-import type { Asset } from '../../core/model/Asset';
+import { type Asset, publicVariables } from '../../core/model/Asset';
 import { findObject } from '../../core/model/hierarchy';
 import {
   type InstanceTarget,
@@ -66,12 +66,12 @@ import { currentProps, currentRef, deviations, positionMoved, targetOf, viewOf }
 import { componentRow, OFFSET_AXES, offsetKey, POSITION_AXES } from './vectorRows';
 
 /**
- * The rows a placed object shows for what it was placed from: a behavior's declared variables, any
- * other asset's schema minus the common switches.
+ * The rows a placed object shows for what it was placed from: a behavior's declared variables but
+ * the private ones (#257), any other asset's schema minus the common switches.
  */
 export function objectRows(project: Project, asset: Asset, object: SceneObject): PropertyDef[] {
   return asset.type === 'behavior'
-    ? asset.variables
+    ? publicVariables(asset)
     : schemaForObject(project, asset, object).filter((def) => !isCommonProp(def.key));
 }
 
@@ -98,7 +98,9 @@ export function objectSignature(
   const rows = schemaForObject(project, asset, object).filter((def) => isRowShown(def, values));
   // A tilemap warns when it is placed more than once, so the number of placements shapes it too.
   const placed = asset.type === 'tilemap' ? `|placed:${findUsages(project, asset.id).length}` : '';
-  return `${object.parentId}|${kind}${placed}|` + rows.map(defSignature).join(',');
+  // A variable turned private leaves the rows, with nothing else about it changed (#257).
+  const hidden = asset.type === 'behavior' ? `|private:${(asset.privateVariables ?? []).join(',')}` : '';
+  return `${object.parentId}|${kind}${placed}${hidden}|` + rows.map(defSignature).join(',');
 }
 
 /** Several objects: what they are, and the actions that apply to all of them at once. */
@@ -240,7 +242,11 @@ export function buildOwnRows(host: InspectorHost, holderId: string, objectId: st
     if (!inTab) header.add(openVariablesButton(host, { kind: 'object', holderId, objectId }));
     host.body.add(header);
   } else if (own.length > 0) addTitle(host, 'PROPERTIES');
-  if (own.length === 0 && behavior) addNote(host, 'The behavior declares no variables.');
+  if (own.length === 0 && behavior)
+    addNote(
+      host,
+      asset.variables.length > 0 ? 'All its variables are private.' : 'The behavior declares no variables.',
+    );
   for (const def of own) propertyRow(host, holderId, objectId, asset, def, values, behavior);
   if (inTab) markObjectRows(host, object, asset, targetOf(project, holderId, objectId));
 }

src/editor/inspector/portSection.ts

@@ -25,6 +25,7 @@ import {
   targetLabel,
   targetProperties,
 } from '../../core/graph';
+import { isPrivateVariable } from '../../core/model/Asset';
 import { findAssetOf, findGraphAsset, type Project } from '../../core/model/Project';
 import { textOf } from '../../core/model/Properties';
 import { DECLARED_PORT_KINDS, VARIABLE_KINDS } from '../../core/properties/kinds';
@@ -115,6 +116,8 @@ export function buildPropertyPortSection(
     choices: behavior ? schemaForAsset(host.state.project, behavior) : [],
     owner: behavior ? `"${behavior.name}"` : 'a behavior',
     empty: id ? 'That behavior is gone.' : 'Pick a behavior first.',
+    // Not offered, yet a port naming one by hand is one of its properties all the same (#257).
+    hidden: (def) => behavior !== undefined && isPrivateVariable(behavior, def.key),
   });
 }
 
@@ -128,14 +131,17 @@ interface PickedPorts {
   custom?: boolean;
   /** Where a choice comes from, shown after its key in the menu; nothing for one that speaks for itself. */
   note?: (def: PropertyDef) => string | undefined;
+  /** A choice left out of the menus that is still valid on a port. */
+  hidden?: (def: PropertyDef) => boolean;
 }
 
 function buildPickedPortSection(
   host: InspectorHost,
   assetId: string,
   node: GraphNode,
-  { noun, choices, owner, empty, custom = false, note }: PickedPorts,
+  { noun, choices, owner, empty, custom = false, note, hidden }: PickedPorts,
 ): void {
+  const offered = hidden ? choices.filter((def) => !hidden(def)) : choices;
   const plural = noun === 'Property' ? 'properties' : 'variables';
   const ports = node.ports ?? [];
   const taken = new Set(ports.map((p) => p.key));
@@ -145,7 +151,7 @@ function buildPickedPortSection(
     return where ? `${def.key} (${where})` : def.key;
   };
   const pick = (own: string, onPick: (port: DeclaredPort) => void): MenuItem[] =>
-    choices.map((def) => ({
+    offered.map((def) => ({
       label: choiceLabel(def),
       disabled: taken.has(def.key) && def.key !== own,
       onSelect: () => onPick(portOf(def)),
@@ -165,7 +171,7 @@ function buildPickedPortSection(
     const items = pick('', (port) => host.state.execute(new AddPortCommand(assetId, node.id, port)));
     new Menu(custom ? typed() : items, { searchable }).openBelow(add);
   };
-  add.setEnabled(custom || choices.some((def) => !taken.has(def.key)));
+  add.setEnabled(custom || offered.some((def) => !taken.has(def.key)));
   header.add(add);
   host.body.add(header);
 

src/editor/inspector/variableRows.ts

@@ -20,6 +20,7 @@ import {
   attachRowActions,
   createField,
   FIELD_INDENT,
+  type Field,
   type FieldHandlers,
   fieldDef,
   type FieldRow,
@@ -31,7 +32,7 @@ import {
   type RowActions,
   structFieldValue,
 } from './fieldFactory';
-import { KIND_ICON_SVG } from '../panels/markIcons';
+import { KIND_ICON_SVG, VARIABLE_SWITCH_ICON_SVG } from '../panels/markIcons';
 import { addNote, type InspectorHost } from './host';
 
 /** The menu every "add a kind" button opens: one entry per kind, named as the kind table names it. */
@@ -51,8 +52,11 @@ export interface VariableEditing {
   addField: (path: readonly string[], kind: NestedKind) => void;
 }
 
-/** A behavior's switch for one variable: carried on from one `Run behavior` call to the next (#229). */
-export interface VariableKeep {
+/**
+ * A behavior's switch for one variable: carried on from one `Run behavior` call to the next (#229),
+ * or hidden from everything outside its graph (#257).
+ */
+export interface VariableSwitch {
   on: boolean;
   set: (on: boolean) => void;
 }
@@ -72,7 +76,8 @@ export interface StructTyping {
 export interface VariableOptions {
   edit?: VariableEditing;
   typing?: StructTyping;
-  keep?: VariableKeep;
+  keep?: VariableSwitch;
+  hidden?: VariableSwitch;
   /** ↺/↑ on the first row: an override covers a whole struct, so its fields share them. */
   actions?: RowActions;
 }
@@ -88,13 +93,15 @@ export function buildVariable(
   handlers: FieldHandlers,
   options: VariableOptions = {},
 ): FieldRow {
-  const { edit, typing, keep, actions } = options;
+  const { edit, typing, keep, hidden, actions } = options;
   const name = nameCell(def.key, 0, edit && ((next) => edit.rename(next)));
   const head = gridRow(0, markLabel(def.kind), name);
   let setValue: (next: PropertyValue) => void = () => {};
   let below: Widget | undefined;
   // A struct with a type has the type's fields: they are changed on the Struct asset, not here.
   const typed = def.kind === 'struct' ? (typing?.typeName(def.structType) ?? null) : null;
+  // A private value is set in its own graph only (#257): shown, but not edited here.
+  const locked = hidden?.on ?? false;
   if (def.kind === 'struct') {
     head.add(new Spacer(), 1);
     if (edit && typed === null) head.add(addFieldMenu(edit, []));
@@ -102,8 +109,10 @@ export function buildVariable(
     const field = createField(host, def, value, handlers);
     setValue = addValue(head, field);
     below = field.below;
+    lockValue(field, locked);
   }
-  if (keep) head.add(keepButton(keep));
+  if (hidden) head.add(switchButton('private', hidden));
+  if (keep) head.add(switchButton('keep', keep));
   if (edit) head.add(removeButton(edit.remove));
   const refreshActions = actions ? attachRowActions(head, actions) : () => {};
   host.body.add(head);
@@ -123,6 +132,7 @@ export function buildVariable(
       handlers,
       own ? edit : undefined,
       own ? typing : undefined,
+      locked,
     );
   }
 
@@ -136,18 +146,26 @@ export function buildVariable(
   };
 }
 
-/** Lit while the variable is kept; a click flips it. */
-function keepButton(keep: VariableKeep): Button {
-  const button = new Button('Keep', {
+/** Lit while the switch is on – the lock while private, the pin while kept; a click flips it. */
+function switchButton(icon: keyof typeof VARIABLE_SWITCH_ICON_SVG, of: VariableSwitch): Button {
+  const button = new Button('', {
     variant: 'ghost',
-    style: 'small',
     toggle: true,
-    onClick: () => keep.set(!keep.on),
+    icon: VARIABLE_SWITCH_ICON_SVG[icon],
+    padding: 4,
+    onClick: () => of.set(!of.on),
   });
-  button.setToggled(keep.on);
+  button.setToggled(of.on);
   return button;
 }
 
+/** A value – and the items below it – greyed out and deaf to the pointer while `locked`. */
+function lockValue(field: Field, locked: boolean): void {
+  if (!locked) return;
+  field.widget.setEnabled(false);
+  field.below?.setEnabled(false);
+}
+
 /**
  * One row per field, each with its own value; a field that is a struct again is a head row with its
  * fields indented below it (#239). `path` names the struct these fields belong to. Returns the
@@ -161,6 +179,7 @@ function structFieldRows(
   handlers: FieldHandlers,
   edit: VariableEditing | undefined,
   typing: StructTyping | undefined,
+  locked: boolean,
 ): (next: PropertyValue) => void {
   const setters = new Map<string, (item: PropertyValue) => void>();
   for (const field of fields) {
@@ -185,6 +204,7 @@ function structFieldRows(
           handlers,
           own ? edit : undefined,
           own ? typing : undefined,
+          locked,
         ),
       );
       continue;
@@ -192,6 +212,7 @@ function structFieldRows(
     const own = handlers.structFieldHandlers?.([...path, field.key], field) ?? READ_ONLY;
     const sub = createField(host, fieldDef(field), item, own);
     setters.set(field.key, addValue(row, sub));
+    lockValue(sub, locked);
     if (edit) row.add(removeButton(() => edit.removeField(path, field)));
     host.body.add(row);
     if (field.kind === 'list' && typing) {

src/editor/panels/icons/keep.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" id="keep" viewBox="-8 -8 16 16" width="16" height="16">
+  <path d="M-3 -7 H3 L2 -2 L4.5 1 H-4.5 L-2 -2 Z" fill="currentColor" />
+  <line x1="0" y1="1" x2="0" y2="7" fill="none" stroke="currentColor" stroke-width="1.5" />
+</svg>

src/editor/panels/icons/private.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" id="private" viewBox="-8 -8 16 16" width="16" height="16">
+  <path d="M-3 -1 V-3.5 A3 3 0 0 1 3 -3.5 V-1" fill="none" stroke="currentColor" stroke-width="1.5" />
+  <rect x="-5" y="-1" width="10" height="7.5" rx="1" fill="currentColor" />
+</svg>

src/editor/panels/markIcons.ts

@@ -19,6 +19,8 @@ import sound from './icons/kind-sound.svg?raw';
 import statemachine from './icons/kind-statemachine.svg?raw';
 import struct from './icons/kind-struct.svg?raw';
 import texture from './icons/kind-texture.svg?raw';
+import keep from './icons/keep.svg?raw';
+import privateLock from './icons/private.svg?raw';
 import reset from './icons/reset.svg?raw';
 
 /** Kinds shown as a picture; the rest keep their mark in letters (`#`, `Aa`). */
@@ -38,5 +40,11 @@ export const KIND_ICON_SVG: Partial<Record<Kind, string>> = {
 
 export const ROW_ACTION_ICON_SVG = { apply, reset, fitWidth, fitHeight };
 
+/**
+ * A behavior variable's two switches: kept from one call to the next (#229), hidden from everything
+ * outside its graph (#257). Pictures, not words: a list's head has no room for both.
+ */
+export const VARIABLE_SWITCH_ICON_SVG = { keep, private: privateLock };
+
 /** A transition row's direction: one leaving the state, one coming in. */
 export const ARROW_ICON_SVG = { out: arrowOut, in: arrowIn };

src/runtime/World.ts

@@ -1,6 +1,6 @@
 import { ENTITY_HANDLE, isHandleEnabled, type PointerState, worldMatrixOf } from '../core/graph';
 import { newId } from '../core/ids';
-import type { Asset, TilemapAsset } from '../core/model/Asset';
+import { type Asset, isPrivateVariable, type TilemapAsset } from '../core/model/Asset';
 import { withoutObjects } from '../core/graph/liveObjects';
 import { bagWithoutItemTypes, type PropertyBag, sameValue, type Vec2 } from '../core/model/Properties';
 import { isPlaceableType } from '../core/model/AssetTypes';
@@ -252,8 +252,11 @@ export class World {
     const resolved = bagWithoutItemTypes(resolveSceneObjectProps(this.project, asset, object));
     for (const key of Object.keys(entity.props)) if (!(key in resolved)) delete entity.props[key];
     // The scene only ever got the objects' empty places, so a value that differs by them alone stays.
-    for (const [key, value] of Object.entries(resolved))
+    // A private value never reaches the scene, so the scene's is only where it starts.
+    for (const [key, value] of Object.entries(resolved)) {
+      if (isPrivateVariable(asset, key) && key in entity.props) continue;
       if (!sameValue(value, withoutObjects(entity.props[key]))) entity.props[key] = value;
+    }
     return entity;
   }
 
@@ -322,9 +325,13 @@ export class World {
       const moved = p.x !== entity.x || p.y !== entity.y || p.z !== entity.z;
       const base = bagWithoutItemTypes(resolveSceneObjectProps(this.project, asset, object));
       // What a run holds of an object stays in the run; the scene gets the empty one.
+      // A private variable (#257) has no override to hold its value: that stays in the run.
       const drifted = Object.keys(entity.props).filter(
         (k) =>
-          k in base && base[k] !== entity.props[k] && !sameValue(base[k], withoutObjects(entity.props[k])),
+          k in base &&
+          !isPrivateVariable(asset, k) &&
+          base[k] !== entity.props[k] &&
+          !sameValue(base[k], withoutObjects(entity.props[k])),
       );
       if (!moved && drifted.length === 0) continue;
       // Only now, because a ref for resolved content costs a resolve of its own – and because a