Family Zoo Tutorial

tutorials/familyzoo/src/v17/
├── index.ts        # Story class — wires everything together
├── zoo-map.ts      # Rooms, exits, scenery, locked door
├── zoo-items.ts    # Portable objects, containers, supporters
├── characters.ts   # Zookeeper, parrot, pettable animals, NPC behaviors
├── events.ts       # PA announcements, feeding time, after-hours daemons
├── scoring.ts      # Score IDs, point values, victory condition
└── language.ts     # All player-facing text

import '@sharpee/helpers';

export function createZooMap(world: WorldModel) {
  const { room, object, door } = world.helpers();

  const entrance = room('Zoo Entrance')
    .description('You stand before the wrought-iron gates of the Willowbrook Family Zoo...')
    .aliases('entrance', 'gates', 'gate')
    .build();

  const mainPath = room('Main Path')
    .description('A wide gravel path winds through the heart of the zoo...')
    .aliases('path', 'main path', 'gravel path')
    .build();

  const nocturnalExhibit = room('Nocturnal Animals Exhibit')
    .description('A cool, dimly lit cavern designed to simulate nighttime...')
    .dark()
    .build();

  const keycard = object('staff keycard')
    .description('A white plastic keycard with "WILLOWBROOK ZOO — STAFF ONLY".')
    .aliases('keycard', 'key card', 'card', 'key')
    .in(entrance)
    .build();

  door('staff gate')
    .description('A sturdy metal gate with a "STAFF ONLY" sign.')
    .aliases('gate', 'staff gate', 'metal gate')
    .between(mainPath, supplyRoom, Direction.SOUTH)
    .openable({ isOpen: false })
    .lockable({ isLocked: true, keyId: keycard.id })
    .build();

  object('welcome sign')
    .description('A brightly painted wooden sign reads: "WELCOME TO WILLOWBROOK FAMILY ZOO."')
    .aliases('sign', 'welcome sign')
    .scenery()
    .in(entrance)
    .build();

export function createZooItems(world: WorldModel, rooms: RoomIds) {
  const { object, container } = world.helpers();

  // Portable light source with custom trait
  const flashlight = object('flashlight')
    .description('A heavy-duty yellow flashlight.')
    .aliases('flashlight', 'torch', 'light')
    .lightSource({ isLit: false })
    .addTrait(new SwitchableTrait({ isOn: false }))
    .in(supplyRoomEntity)
    .build();

  // Container
  const lunchbox = container('lunchbox')
    .description('A dented metal lunchbox decorated with cartoon zoo animals.')
    .aliases('lunchbox', 'lunch box', 'box')
    .openable({ isOpen: false })
    .in(mainPathEntity)
    .build();

  // Place item inside a closed container (bypasses validation)
  const juice = object('juice box')
    .description('A small juice box with a picture of a happy elephant.')
    .aliases('juice', 'juice box', 'drink')
    .skipValidation()
    .in(lunchbox)
    .build();

export function createCharacters(world: WorldModel, rooms: RoomIds) {
  const { actor, object } = world.helpers();

  const zookeeper = actor('zookeeper')
    .description('A friendly zookeeper in khaki overalls. A name tag reads "Sam."')
    .aliases('keeper', 'zookeeper', 'sam')
    .addTrait(new NpcTrait({
      behaviorId: KEEPER_PATROL_ID,
      canMove: true, isAlive: true, isConscious: true,
    }))
    .in(mainPathEntity)
    .build();

const keeperPatrol = createPatrolBehavior({
  route: [this.roomIds.mainPath, this.roomIds.pettingZoo, this.roomIds.aviary],
  loop: true,
  waitTurns: 1,
});
keeperPatrol.id = KEEPER_PATROL_ID;
npcService.registerBehavior(keeperPatrol);

export class PettableTrait implements ITrait {
  static readonly type = 'zoo.trait.pettable' as const;
  static readonly capabilities = ['zoo.action.petting'] as const;
  readonly type = PettableTrait.type;
  readonly animalKind: AnimalKind;
  constructor(kind: AnimalKind) {
    this.animalKind = kind;
  }
}

const pettingBehavior: CapabilityBehavior = {
  validate(entity, world, actorId, sharedData) {
    return { valid: true };
  },
  execute(entity, world, actorId, sharedData) { },
  report(entity, world, actorId, sharedData) {
    const pettable = entity.get(PettableTrait);
    let messageId = PetMessages.CANT_PET;
    switch (pettable?.animalKind) {
      case 'goats':   messageId = PetMessages.PET_GOATS; break;
      case 'rabbits': messageId = PetMessages.PET_RABBITS; break;
      case 'parrot':  messageId = PetMessages.PET_PARROT; break;
    }
    return [createEffect('zoo.event.petted', { messageId, params: { target: entity.name } })];
  },
  blocked(entity, world, actorId, error, sharedData) {
    return [createEffect('zoo.event.petting_blocked', { messageId: error })];
  },
};

extendParser(parser: Parser): void {
  const grammar = parser.getStoryGrammar();
  grammar.define('feed :thing').mapsTo(FEED_ACTION_ID).withPriority(150).build();
  grammar.define('photograph :thing').mapsTo(PHOTOGRAPH_ACTION_ID).withPriority(150).build();
  grammar.define('photo :thing').mapsTo(PHOTOGRAPH_ACTION_ID).withPriority(150).build();
  grammar.define('pet :thing').mapsTo(PETTING_ACTION_ID).withPriority(150).build();
  grammar.define('stroke :thing').mapsTo(PETTING_ACTION_ID).withPriority(150).build();
}

// PA announcement daemon — fires every 5 turns, counts down to close
export function createPAAnnouncementDaemon(): Daemon {
  let announcementCount = 0;
  return {
    id: 'zoo.daemon.pa_announcements',
    name: 'Zoo PA Announcements',
    priority: 5,
    condition: (ctx) => ctx.turn > 0 && ctx.turn % 5 === 0 && announcementCount < 4,
    run: (ctx) => {
      announcementCount++;
      // On the 4th announcement, flip the after-hours flag
      if (announcementCount === 4) {
        ctx.world.setStateValue('zoo.after_hours', true);
      }
      return [{ /* message event */ }];
    },
  };
}

// Runtime behavior swap — the canonical way to change NPC behavior mid-game
scheduler.registerDaemon({
  id: 'zoo.daemon.parrot_behavior_swap',
  condition: (ctx) => !behaviorSwapped && ctx.world.getStateValue('zoo.after_hours') === true,
  run: () => {
    behaviorSwapped = true;
    npcService.removeBehavior('zoo-parrot');
    npcService.registerBehavior(parrotAfterHoursBehavior);
    return [];
  },
});

world.chainEvent('if.event.actor_moved', (event, w) => {
  const toRoom = event.data.toRoom || event.data.destination;
  const roomEntity = w.getEntity(toRoom);
  const roomName = roomEntity?.get(IdentityTrait)?.name || '';
  const scoreId = ROOM_SCORE_MAP[roomName];
  if (scoreId) w.awardScore(scoreId, ScorePoints[scoreId], `Visited ${roomName}`);
  return null;
}, { key: 'zoo.chain.room-visit-scoring' });

export function registerMessages(language: LanguageProvider): void {
  language.addMessage(FeedMessages.FED_GOATS,
    'You scatter some feed on the ground. The pygmy goats rush over, bleating excitedly...');

  language.addMessage(AfterHoursMessages.PARROT_CANDID,
    'The parrot clears its throat and fixes you with a knowing look. "Right then. Now that the '
    + 'performative squawking is over, let me tell you something..."');

  language.addMessage(ScoreMessages.VICTORY,
    'Congratulations! You\'ve earned your MASTER ZOOKEEPER badge! *** You have won ***');
}

> look
Zoo Entrance
You stand before the wrought-iron gates of the Willowbrook Family Zoo...

> take brochure
Taken.

> read brochure
WILLOWBROOK FAMILY ZOO — Your Guide...

> south
Main Path
A wide gravel path winds through the heart of the zoo...

> east
Petting Zoo
A cheerful open-air enclosure filled with friendly animals...

> take feed
Taken.

> feed goats
You scatter some feed on the ground. The pygmy goats rush over...

> pet rabbits
You gently stroke one of the rabbits. Its fur is incredibly soft...

> west. west
Aviary
You step inside a soaring mesh dome...

> pet parrot
CHOMP! It nips your finger with its beak. "NO TOUCHING!" it squawks.