postal

name	postal
description	Complete messaging system — letters, texts, goals, rewards, attachments
allowed-tools	["read_file","write_file"]
tier	1
protocol	POSTAL-SYSTEM
tags	["moollm","mail","message","goals","rewards","attachments","phone","communication"]
related	["goal","character","object","room","storage","buff"]
adversary	instant-coupling

Postal System

"Any address can send and receive. Goals come from anyone, not just Mom." — The Gezelligheid Grotto Design Principles

---

What Is It?

The Postal System is the complete messaging infrastructure:

Feature	Description
Messages	Letters between any endpoints
Texts	SMS-style instant messages
Attachments	Items, gold, images, buffs, room access
Goals	Any character can assign/modify/complete goals
Phone	Always-available mobile access (it's 2026!)
Routing	Deterministic delivery without LLM

---

Core Concepts

Endpoints

Anything addressable can send/receive:

to: "player"                       # Reserved keyword
to: "characters/family/mom/"       # Character path
to: "characters/npcs/bartender/"   # Any NPC
to: "pub/"                         # Room
to: "storage/vault/"               # Directory
to: "start/mailbox.yml"            # Object

Deterministic Addressing

CRITICAL: Addresses are paths, not names. The simulator routes without LLM.

# BAD: Symbolic (requires LLM)
from: mom
to: the bartender

# GOOD: Deterministic paths
from: "characters/family/mom/"
to: "characters/npcs/bartender/"

Reserved Keywords

Keyword	Resolves To
player	Current player character
party	All party members
narrator	System/narrative voice

---

It's 2026 — You Have a Phone!

You carry a phone at all times. Mail and texts are always available.

player:
  devices:
    phone:
      always_carried: true
      capabilities: [mail, text, notifications, camera, maps]

Notification Types

Type	Example
📬 Mail	"New letter from Mom!"
💬 Text	"Don: Meet me at the pub"
🎯 Quest	"Quest updated: Find the Key"
⚠️ Alert	"WARNING: Grue nearby!"
🎁 Reward	"You received: Gold Coins (50)"

---

Letters (Full Messages)

Structure

letter:
  id: "letter-001"
  from: "characters/family/mom/"
  to: "player"
  subject: "Your First Quest"
  
  body: |
    Dearest child,
    
    I need you to find something for me.
    There's a brass key somewhere in the maze.
    
    With love,
    Mom
    
  attachments: []
  
  # Goal integration (optional — ANY character can do this!)
  creates_goal:
    id: find-key
    name: "Find the Key"
    complete_when: "player has brass-key"
    reward:
      letter: mom-reward-001
      item: family-locket
      
  # Metadata
  sent: null
  delivered: null
  read: false
  status: draft  # draft | outbox | sent | delivered | read

Goal Integration

Any character can create/modify/complete goals — not just Mom:

# Bartender assigns a quest
letter:
  from: "characters/npcs/bartender/"
  to: "player"
  subject: "A Favor to Ask"
  body: "Could you deliver this package to the mayor?"
  
  creates_goal:
    id: deliver-package
    name: "Deliver the Package"
    complete_when: "player has talked to mayor with package"
    reward:
      gold: 50
      
# Don Hopkins updates your quest
letter:
  from: "characters/real-people/don-hopkins/"
  to: "player"
  subject: "Found something!"
  
  modifies_goal:
    id: find-key
    extend_with: "also check the old chest"

---

Texts (Instant Messages)

Short, instant messages. It's 2026!

text:
  id: "text-001"
  from: "characters/npcs/bartender/"
  to: "player"
  body: "Hey, you left your hat here!"
  
  quick_replies:
    - "On my way!"
    - "Thanks, be there soon"
    - "Can you hold it?"
    
  delivery: instant  # Not queued like letters
  timestamp: null
  read: false

Texts vs Letters

Feature	Text	Letter
Length	Short (< 160)	Long
Attachments	Photos only	Anything
Delivery	Instant	Next tick
Creates goals	Rarely	Yes
Formality	Casual	Can be formal

---

Attachments

Messages can carry anything:

attachments:
  # Objects
  - type: object
    ref: "brass-key"
    action: send       # Remove from sender, give to recipient
    
  - type: object
    ref: "map"
    action: reference  # Just mention, don't transfer
    
  # Currency
  - type: gold
    quantity: 100
    action: send
    
  # Images
  - type: image
    ref: "images/treasure-map.png"
    action: copy
    
  - type: image
    action: generate
    prompt: "A hand-drawn map to the treasure..."
    
  # Buffs
  - type: buff
    ref:
      name: "Blessed"
      effect: "+1 luck"
      duration: 10
    action: apply
    
  # Room access
  - type: room
    ref: "maze/secret-chamber/"
    action: unlock

Attachment Actions

Action	Effect
send	Remove from sender, give to recipient
give	Give to recipient (sender keeps if applicable)
copy	Duplicate for recipient
reference	Mention without transfer
unlock	Grant access (for rooms)
apply	Apply effect (for buffs)
generate	Create on delivery (for images)

---

Inbox & Outbox

Inbox

# player/INBOX.yml
inbox:
  owner: "player"
  
  messages:
    - ref: "messages/mom-quest.yml"
      received: "2026-01-10T10:00:00Z"
      read: false
      priority: high
      from: "characters/family/mom/"
      subject: "Your First Quest"
      preview: "Dearest child, I need you to..."
      
  unread_count: 1
  
  settings:
    max_messages: 100
    forward_to: null

Outbox (Optional)

Stage messages before sending:

# player/OUTBOX.yml
outbox:
  owner: "player"
  
  drafts:
    - ref: "messages/draft-001.yml"
      started: "2026-01-10T09:00:00Z"
      
  pending:
    - ref: "messages/ready-001.yml"
      to: "characters/family/mom/"

---

Delivery Simulation

The postal system simulates realistic delivery:

Delivery Time

Messages don't arrive instantly (unless texting!):

letter:
  from: "characters/family/mom/"
  to: "player"
  
  # Delivery simulation
  delivery:
    method: letter           # letter, express, text
    
    # Time calculation
    base_time: 3             # Base turns
    distance_factor: 1       # Turns per "hop" of distance
    total_time: 5            # Calculated: base + (distance * factor)
    
    # Timestamps
    sent: "2026-01-10T10:00:00Z"
    estimated_arrival: "2026-01-10T10:05:00Z"  # 5 turns later
    delivered: null          # Set when actually delivered
    
    # Status
    status: in_transit       # draft | outbox | in_transit | delivered | read
    turns_remaining: 5

Delivery Methods

Method	Base Time	Cost	Features
text	0 (instant)	Free	Photos only, casual
letter	3 turns	1 gold	Full attachments, goals
express	1 turn	5 gold	Priority delivery
freight	10 turns	0.5 gold/kg	Heavy items, bulk
courier	2 turns	10 gold	Guaranteed, tracked

Distance Calculation

Distance is measured in "hops" through the room graph:

# Distance examples:
# Same room: 0 hops
# Adjacent room: 1 hop
# Through maze: 5+ hops
# Different "region": 10+ hops

delivery:
  from_location: "pub/"
  to_location: "characters/family/mom/"  # Mom's home
  hops: 4
  time_per_hop: 1
  total_delivery_time: 7  # base 3 + (4 * 1)

Postage Costs

Sending mail costs resources:

letter:
  from: "player"
  to: "characters/family/mom/"
  
  postage:
    method: letter
    base_cost: 1             # Gold
    weight_cost: 0           # Per kg for heavy items
    distance_cost: 0.5       # Per hop
    total_cost: 3            # Calculated
    
    # Payment
    paid: false
    paid_from: "player"      # Who pays
    
    # Insufficient funds?
    requires_payment: true
    can_send: true           # false if can't afford

Free Messaging

Some messages are free:

# Texts are free
text:
  postage:
    method: text
    total_cost: 0
    
# System messages are free
letter:
  from: "narrator"
  postage:
    total_cost: 0
    reason: "system message"
    
# Within same location is free
letter:
  from: "pub/bartender.yml"
  to: "pub/patron.yml"
  postage:
    total_cost: 0
    reason: "same location"

In-Transit Tracking

Track messages in transit:

# world.skills.postal state
postal:
  in_transit:
    - id: letter-001
      from: "player"
      to: "characters/family/mom/"
      turns_remaining: 3
      
    - id: letter-002
      from: "characters/npcs/bartender/"
      to: "player"
      turns_remaining: 1
      
  # Each tick, turns_remaining decrements
  # When 0, message is delivered

Delivery Simulation in Tick

# MAIL phase of simulation
def deliver_mail(world):
    postal = world.skills.postal
    
    # Decrement turns for in-transit messages
    still_in_transit = []
    for message in postal.get('in_transit', []):
        message['turns_remaining'] -= 1
        
        if message['turns_remaining'] <= 0:
            # Deliver now!
            actually_deliver(world, message)
            world.trigger_event('MAIL_ARRIVED', {
                'from': message['from'],
                'to': message['to']
            })
        else:
            still_in_transit.append(message)
    
    postal['in_transit'] = still_in_transit

Express & Priority

Pay more for faster delivery:

letter:
  delivery:
    method: express
    
  postage:
    base_cost: 5             # Express premium
    guaranteed_time: 1       # Arrives next turn
    tracking: true           # Can check status
    insurance: true          # Compensated if lost

Lost Mail (Optional Mechanic)

For added realism/drama:

postal:
  settings:
    loss_chance: 0.01        # 1% chance of loss
    loss_recoverable: true   # Can be found later
    
    # Lost mail goes to:
    lost_mail_location: "maze/lost-and-found/"

---

Deterministic Routing

The simulator delivers mail without LLM. See ROUTING.md.

Routing Instructions

letter:
  from: "characters/family/mom/"
  to: "player"
  
  # Generated routing (deterministic)
  routing:
    destination_type: player
    destination_path: player
    delivery_point: inbox
    inbox_path: player/INBOX.yml
    
    attachments_transfer:
      - type: object
        ref: "brass-key"
        action: send
        from_inventory: "characters/family/mom/"
        to_inventory: "player"
        
    triggers:
      - event: MESSAGE_RECEIVED
        data: { from: "characters/family/mom/" }
      - event: GOAL_CREATED
        data: { goal_id: find-key }

Simulation Phase

Mail delivery is a phase in the simulation tick:

1. RESET     — foo_effective = foo
2. BUFFS     — Apply modifiers
3. SIMULATE  — Objects run
4. MAIL      — Deliver queued messages (deterministic!)
5. EVENTS    — Process queue
6. NAVIGATE  — Move player
7. DISPLAY   — Update UI

---

Storage Integration

Mail items to your vault:

letter:
  from: "player"
  to: "storage/vault/"
  subject: "Depositing treasure"
  
  attachments:
    - type: gold
      quantity: 500
      action: send

---

Logistics Integration — Postal IS the Transport Layer!

KEY INSIGHT: You don't need physical bots to move items between logistic containers. The postal system IS the transport layer — instantaneous, free, efficient!

The Unification

Factorio	MOOLLM
Logistics bots	Postal system (free, instant)
Flying between chests	Email/text delivery
Request list	Triggers automated mail
Active provider pushing	Auto-send attachments
Circuit signals	Text notifications

How It Works

When a logistics requester needs items, instead of dispatching a bot:

# Automatic postal delivery for logistics
logistics_delivery:
  trigger: "requester.request_unfulfilled"
  
  # Find a provider with matching items
  provider: "nw/iron-ore/"
  requester: "forge/"
  item: "iron-ore"
  count: 20
  
  # Generate a postal transfer (instant, free!)
  postal_transfer:
    type: internal-logistics    # Special type: no cost, instant
    from: "nw/iron-ore/"
    to: "forge/"
    attachments:
      - type: object
        ref: "iron-ore"
        quantity: 20
        action: send
        
    # No delivery time for internal logistics!
    delivery:
      method: logistics         # New method: instant, free
      total_time: 0
      cost: 0

Logistics Delivery Methods

Method	Time	Cost	Use Case
logistics	0	Free	Internal network transfers
text	0	Free	Signals, notifications
letter	3+ turns	1+ gold	Player-to-player with drama
freight	10+ turns	Per weight	Physical bulk transport

Camera Phone = Image Generation!

Your phone's camera can generate images via prompts:

text:
  from: "player"
  to: "narrator"
  body: "Take a photo of this treasure map"
  
  attachments:
    - type: image
      action: generate
      prompt: "A weathered treasure map showing the maze layout..."
      save_to: "player/photos/treasure-map.png"

Text Messages = Circuit Signals!

Texts can carry logistics signals:

# Room emits signal when low on fuel
room:
  signals:
    enabled: true
    emit:
      - signal: "low-fuel"
        when: "stacks.coal < 5"
        action:
          text:
            to: "player"
            body: "⚠️ Forge is running low on coal!"

No Bots Needed (But You Can Have Them!)

Default: Logistics uses postal (instant, free) Optional: Physical bots for gameplay/drama

logistic-container:
  transport:
    method: postal           # Default: instant via mail
    # OR
    method: bot              # Physical transport (slower, visible)
    bot_path: "characters/courier-kitten/"

When using bots:

• Player sees the kitten carrying items
• Can intercept, pet, or redirect
• Adds gameplay and drama
• But slower than postal!

The Complete Flow

1. REQUESTER: "I need 20 iron ore"
   │
   ▼
2. LOGISTICS ENGINE finds provider with iron ore
   │
   ▼
3. Generate POSTAL TRANSFER (internal, instant, free)
   │
   ├─── method: postal ────→ Instant delivery
   │                         No physical movement
   │                         Items "teleport"
   │
   └─── method: bot ───────→ Dispatch courier kitten
                             Physical movement
                             Player can see/interact
   │
   ▼
4. REQUESTER receives items
   │
   ▼
5. on_request_fulfilled fires

Why This Is Better

Physical Bots	Postal Transport
Slow (travel time)	Instant
Visible (might break immersion)	Invisible (just works)
Can get stuck	Never fails
Limited cargo	Unlimited
Fun to watch	Efficient

Use bots for drama. Use postal for efficiency.

---

Commands

Command	Effect
CHECK PHONE	See notifications and quick access
READ MAIL	Open inbox
READ [letter]	Display letter
COMPOSE	Start writing
REPLY	Reply to current
ATTACH [item]	Add attachment
SEND	Send current message
TEXT [character]	Quick text

---

Mom as a Character

Mom isn't special infrastructure — she's just a character:

# characters/family/mom/CHARACTER.yml
character:
  id: mom
  name: "Mom"
  type: correspondent
  
  personality:
    warmth: 10
    worry: 7
    pride: 9
    
  voice:
    patterns:
      - "Dearest child"
      - "I'm so proud"
      - "Be careful out there"
      
  triggers:
    on_goal_complete: "Send congratulations letter"
    on_danger: "Send worried letter"
    on_long_silence: "Send 'are you okay?' letter"

Any character can have similar triggers. The bartender can send quests. Don Hopkins can send updates. Goals come from anyone!

---

Browser UI

See BROWSER-UI.md for the delightful mail interface.

---

Protocol Symbol

POSTAL-SYSTEM — Complete messaging with deterministic routing