playbooks

home / skills / simhacker / moollm / advertisement

advertisement skill

/skills/advertisement

This skill reveals how objects advertise their possible actions to users and autonomous agents, improving interaction, planning, and context-aware decisions.

npx playbooks add skill simhacker/moollm --skill advertisement

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
7.3 KB
---
name: advertisement
description: Objects announce what they can do — The Sims style
allowed-tools:
  - read_file
  - write_file
  - list_dir
tier: 1
protocol: ADVERTISEMENT
related: [card, object, society-of-mind, room, action-queue, coherence-engine, needs]
tags: [moollm, game, interaction, sims, behavior, autonomy]
---

# Advertisement

> *"Objects don't wait to be used — they announce what they can do."*

---

## What Is It?

**Advertisement** is The Sims-style object interaction: every object in a room broadcasts its available actions, scored by relevance to the current context.

Instead of the user memorizing commands, objects **advertise** what's possible:

```
You approach the workbench.

Available actions (sorted by relevance):
  ⭐ CRAFT tool (you have materials)
  • EXAMINE blueprints
  • ORGANIZE parts
  • MORE options...
```

---

## The Sims Connection

In **The Sims**, objects have "advertisements" — each interaction scores based on:
- The Sim's current needs (hunger, fun, social)
- Object properties (a fridge scores high for hunger)
- Context (can't use stove if broken)

This extensible object architecture was **key to The Sims' massive success**:
- **User-created objects** — anyone could make new furniture, appliances, characters
- **Expansion packs** — just drop in new objects with their advertisements
- **No code changes** — objects self-describe their behaviors
- **Infinite variety** — the community created millions of objects

The same YAML file that defines what an object *is* also defines what it *can do*. Plug-in architecture for free.

MOOLLM applies this to **any object**:

```yaml
# workbench.yml
type: object
advertisements:
  - action: CRAFT
    score_if: "has_materials AND has_skill"
    satisfies: [productivity, creativity]
    
  - action: EXAMINE
    score_if: "always"
    satisfies: [curiosity]
    
  - action: MORE
    score_if: "always"
    satisfies: [exploration]
```

---

## How It Works

### 1. Objects Broadcast

Every object in the room has an `advertisements` list:

```yaml
advertisements:
  - action: USE
    description: "Activate this tool"
    preconditions: [in_inventory, charged]
    score: 80
    
  - action: EXAMINE
    description: "Look closely"
    preconditions: []  # always available
    score: 50
```

### 2. Context Scores

Scores adjust based on:
- **Character needs** — hungry character scores FOOD higher
- **Current goals** — research goal scores EXAMINE higher
- **Environment** — dark room scores LIGHT higher

### 3. Pie Menu Appears

Top actions surface in the [PIE-MENU](../room/):

```
    [CRAFT]
       ⭐
[ORGANIZE] • [EXAMINE]
       •
    [MORE]
```

Center = highest score = default action.

---

## Autonomous Selection

For **autonomous agents**, advertisements enable self-direction:

```
Agent evaluates all objects in room:
  workbench: CRAFT (85), EXAMINE (50)
  bookshelf: READ (70), ORGANIZE (30)
  door: EXIT (40)
  
Agent selects: CRAFT at workbench (score 85)
```

No hardcoded behavior. Objects define possibilities. Agent selects based on goals.

---

## Example: Smart Room

```yaml
# research-lab/ROOM.yml
objects:
  - microscope:
      advertisements:
        - action: ANALYZE_SAMPLE
          score_if: "has_sample"
          score: 90
        - action: CALIBRATE
          score_if: "accuracy < 0.9"
          score: 60
          
  - notebook:
      advertisements:
        - action: WRITE_NOTES
          score_if: "has_observations"
          score: 75
        - action: REVIEW
          score: 40
          
  - coffee_maker:
      advertisements:
        - action: BREW
          score_if: "fatigue > 0.3"
          score: 65
        - action: CLEAN
          score_if: "uses > 5"
          score: 30
```

Agent enters, sees:
```
Top actions:
  1. ANALYZE_SAMPLE at microscope (90) — you have a sample!
  2. WRITE_NOTES at notebook (75) — observations pending
  3. BREW at coffee_maker (65) — you're a bit tired
```

---

## SimAntics Heritage

This is **SimAntics** — The Sims' behavioral engine:

| SimAntics | MOOLLM |
|-----------|--------|
| Object advertisement | `advertisements:` list in YAML |
| Motive scores | Context-based scoring |
| Autonomous selection | Agent picks highest-scored action |
| Pie menu | [PIE-MENU](../room/) for user interaction |

Don Hopkins worked on SimAntics. This is that tradition, for LLM agents.

---

## HyperCard-Style Event Bubbling

When you click an advertised action, it triggers a **symbolic event** that bubbles up:

```
Click CRAFT on workbench

Event path:
  1. workbench (object)     → handles CRAFT? no, pass up
  2. workshop/ (room)       → handles CRAFT? no, pass up  
  3. building/ (parent)     → handles CRAFT? no, pass up
  4. world/ (root)          → handles CRAFT? no, check inheritance
  5. workbench-prototype    → handles CRAFT? YES → execute
```

Just like HyperCard: events bubble from button → card → background → stack.

### Containment Tree (Spatial)

Events bubble **up** the room hierarchy:

```
object in room in parent-room in world
   ↑         ↑              ↑        ↑
              event bubbles up
```

### Inheritance Graph (Prototype)

If no handler in containment tree, check the **prototype chain**:

```
workbench
   ↓ inherits from
furniture-prototype  
   ↓ inherits from
object-prototype     → has default CRAFT handler!
```

### Combined Path

```yaml
# Event resolution order:
1. The object itself
2. Parent room
3. Grandparent room
4. ... up to world root
5. Object's prototype
6. Prototype's prototype
7. ... up to root prototype
```

First handler that responds wins. Unhandled events can:
- Log a warning
- Trigger POSTEL (charitable interpretation)
- Invoke a default handler

### Example: Custom Behavior

```yaml
# workshop/ROOM.yml
handles:
  CRAFT: |
    # Room-level craft handler
    Check if character has required skill.
    Check if materials available in room.
    If conditions met, delegate to object.
    Otherwise, suggest where to get materials.
```

The room intercepts CRAFT before it reaches the object, adding room-specific logic.

---

## Dovetails With

- [Room](../room/) — Where objects live and advertise
- [PIE-MENU](../room/) — How advertisements surface to users
- [SNAP-CURSOR](../room/) — Context-aware object interaction
- [Coherence Engine](../coherence-engine/) — Evaluates and selects actions
- [Trading Card](../card/) — Cards can advertise too
- [Rubric](../rubric/) — **Scoring criteria** for advertisement evaluation
- [Scoring](../scoring/) — How scores are calculated and valued

---

## Protocol Symbols

```
ADVERTISEMENT        — Objects announce available actions
AUTONOMOUS-SELECTION — Agent picks based on scores
SIMANTICS            — The Sims behavioral model
PIE-MENU             — Radial display of options
FLY-UNDER-RADAR      — Normalize through defaults
PROCEDURAL-RHETORIC  — Rules carry ideology
```

See: [PROTOCOLS.yml](../../PROTOCOLS.yml)

---

## The Deep Insight

From [SIMANTICS](../../PROTOCOLS.yml):

> *"The Sims' AI isn't centralized — it's distributed throughout objects."*
> *"A refrigerator knows it offers food. A bed knows it offers sleep."*
> *"The Sim chooses from what's advertised nearby."*

This IS MOOLLM's architecture. Objects self-describe. The coherence engine orchestrates. Intelligence is **distributed** throughout the world.

The advertisements ARE the AI.

Overview

This skill implements The Sims–style object advertisements: objects in a space broadcast their available actions, scored by relevance to context and agent goals. It lets agents and users see a prioritized list of possible interactions without memorizing commands. The system is YAML-driven and extensible so new objects immediately self-describe their behaviors.

How this skill works

Each object includes an advertisements list that names actions, preconditions, descriptions, and base scores. The coherence engine adjusts those scores by character motives, goals, and environment, then surfaces top actions in a pie-menu or hands them to autonomous agents. When an advertised action is invoked, a symbolic event bubbles up the containment tree and then checks the prototype chain until a handler executes.

When to use it

  • When you want distributed, data-driven behavior for interactive objects
  • To give agents context-aware choices without hardcoding behaviors
  • To expose player or agent UIs with prioritized, relevant actions
  • When creating moddable worlds where user objects add functionality
  • To prototype autonomous selection policies using scored options

Best practices

  • Define clear preconditions and intent tags for each advertisement to improve scoring accuracy
  • Keep descriptions short and user-facing; use separate fields for implementation logic
  • Model motives and goals explicitly so the coherence engine can weight actions correctly
  • Provide default handlers in prototypes to avoid unhandled events
  • Use room-level handlers to implement shared constraints or suggestions

Example use cases

  • A workshop where a workbench advertises CRAFT, EXAMINE, and ORGANIZE and agents pick the highest-scored task
  • A research lab where instruments advertise ANALYZE_SAMPLE or CALIBRATE depending on inventory and status
  • A smart home where appliances advertise actions based on occupant needs (BREW when fatigue is high)
  • A moddable game where community objects drop in with their own advertisements and appear automatically in the pie-menu
  • Autonomous NPCs scanning a room and selecting activities by comparing aggregated scores across objects

FAQ

How are scores computed?

Base scores come from object YAML; the coherence engine modifies them using motives, current goals, and environmental context to produce final relevance scores.

What happens if no handler exists for an advertised action?

Events bubble up containment and prototype chains; if still unhandled, the system can log a warning, apply a default handler, or use POSTEL-style graceful fallback.