Sharpee Platform Status

// Scope levels (highest = most restrictive)
enum ScopeLevel {
  UNAWARE  = 0,  // Entity not known to player
  AWARE    = 1,  // Player knows it exists (can hear/smell)
  VISIBLE  = 2,  // Player can see it
  REACHABLE = 3, // Player can touch it
  CARRIED  = 4,  // In player's inventory
}

// Grammar: declares ONLY semantic constraints
grammar.forAction('if.action.opening')
  .verbs(['open'])
  .pattern(':target')
  .hasTrait('target', TraitType.OPENABLE)  // What kind of thing
  .build();

// Action: enforces scope dynamically
validate(context) {
  const check = context.requireScope(target, ScopeLevel.REACHABLE);
  if (!check.ok) return check.error!;
}

// Player types: "wear hat" (hat is on the floor, not in inventory)
// Engine: "(first taking the hat)" -> then wears it

const result = context.requireCarriedOrImplicitTake(item);
if (!result.ok) return result.error!;
// Applied to: dropping, inserting, giving, showing, throwing, wearing

// Article selection by noun type
{a:item}  // common -> "a sword" / "an apple"
          // proper -> "Excalibur" (no article)
          // mass -> "some water"

// List formatting with Oxford comma
{a:items:list}      // "a sword, a key, and a lantern"
{the:items:or-list} // "the north, the south, or the west"

// Perspective placeholders (42 template files updated)
'taken': "{You} {take} {the:item}."
// 2nd person: "You take the sword."
// 1st person: "I take the sword."
// 3rd person: "She takes the sword."

// Either pattern works through the same API
description: "You are in a dark room"          // Literal text
description: "dungeo.msg.room.west_house"      // Message ID (localized)

// Single unified call handles both
const text = textService.getEntityText(entity, 'description', {}, world);

// Key lesson: trait properties like cantTakeMessage must use
// message IDs, not literal strings, to avoid dot-heuristic misrouting

interface TurnPlugin {
  id: string;
  priority: number;  // NPC=100, StateMachine=75, Scheduler=50
  onAfterAction(context: TurnPluginContext): ISemanticEvent[];
  getState?(): unknown;   // For save/restore
  setState?(state: unknown): void;
}

// Save format preserves plugin state alongside world state
{ worldState: {...}, pluginStates: { scheduler: {...}, stateMachine: {...} } }

// PC attacks NPC:
attacking.ts -> ActionInterceptor -> MeleeInterceptor (Dungeon)
                                  -> BasicCombatInterceptor (generic)

// NPC attacks PC:
npc-service.ts -> NpcCombatResolver -> meleeNpcResolver (Dungeon)
                                    -> basicNpcResolver (generic)

// No combat extension loaded:
"Violence is not the answer." // validation block

// Chain: opening a container automatically reveals contents
world.chainEvent('if.event.opened', (event, world) => {
  const items = getVisibleContents(event.data.entityId);
  if (items.length === 0) return null;
  return { type: 'if.event.revealed', data: { items } };
}, { mode: 'keyed', key: 'stdlib.chain.opened-revealed' });

// Transaction grouping
//   if.event.opened   { transactionId: 'txn-123', chainDepth: 0 }
//   if.event.revealed  { transactionId: 'txn-123', chainDepth: 1 }

// Before: Generic action.success with messageId
world.createEvent('action.success', { messageId: 'if.action.taking.taken' });

// After: Domain event with typed data
world.createEvent('if.event.took', {
  messageId: 'if.action.taking.taken',
  params: { item: itemName, container: containerName },
});

// Key fix: NPC template substitution (ISSUE-054)
// Must include params: action.data in npc.spoke/npc.emoted events