Guest API

Guest entity APIs for managing park visitors in OpenRCT2

Guests are park visitors that can be found using map.getAllEntities('guest'). Each guest has properties controlling their appearance, needs, thoughts, and items.

Accessing Guests

// Get all guests
const guests = map.getAllEntities('guest');

// Get a specific guest by ID
const guest = map.getEntity(guestId);

// Get guests on a specific tile
const guestsOnTile = map.getAllEntitiesOnTile('guest', { x: 64, y: 64 });

Appearance Properties

name · string

Name of the guest.

guest.name = 'John Smith';
console.log(`Guest: ${guest.name}`);

tshirtColour · number

Colour of the guest’s t-shirt (0-31).

guest.tshirtColour = 10; // Change shirt color

trousersColour · number

Colour of the guest’s trousers (0-31).

guest.trousersColour = 5;

balloonColour · number

Colour of the guest’s balloon if they have one.

guest.balloonColour = 3;

hatColour · number

Colour of the guest’s hat if they have one.

guest.hatColour = 7;

umbrellaColour · number

Colour of the guest’s umbrella if they have one.

guest.umbrellaColour = 12;

Status Properties

happiness · number

How happy the guest is (0-255). Higher is happier.

console.log(`Happiness: ${guest.happiness}`);
guest.happiness = 255; // Make guest very happy

happinessTarget · number

The target happiness value. Happiness slowly moves towards this value.

guest.happinessTarget = 200;

energy · number

How tired the guest is (32-128). Lower values mean more tired.

console.log(`Energy: ${guest.energy}`);

energyTarget · number

The target energy value.

guest.energyTarget = 120;

nausea · number

How nauseated the guest is (0-255). Higher values mean more nauseated.

if (guest.nausea > 200) {
  console.log(`${guest.name} feels very sick!`);
}

nauseaTarget · number

The target nausea value.

guest.nauseaTarget = 0; // Target feeling better

hunger · number

How hungry the guest is (0-255). Lower values mean more hungry.

if (guest.hunger < 100) {
  console.log(`${guest.name} is hungry`);
}

thirst · number

How thirsty the guest is (0-255). Lower values mean more thirsty.

if (guest.thirst < 100) {
  console.log(`${guest.name} is thirsty`);
}

toilet · number

How much the guest needs the toilet (0-255). Higher values mean more urgent.

if (guest.toilet > 180) {
  console.log(`${guest.name} needs a toilet!`);
}

mass · number

The mass of the guest. Affects vehicle mass on rides.

console.log(`Mass: ${guest.mass}`);

Preferences

minIntensity · number

The guest’s minimum preferred intensity (0-15).

console.log(`Min intensity: ${guest.minIntensity}`);

maxIntensity · number

The guest’s maximum preferred intensity (0-15).

console.log(`Max intensity: ${guest.maxIntensity}`);

nauseaTolerance · number

The guest’s tolerance to nauseating rides (0-3).

console.log(`Nausea tolerance: ${guest.nauseaTolerance}`);

favouriteRide · number | null

The ride ID of the guest’s favourite ride, or null if none.

if (guest.favouriteRide !== null) {
  const ride = map.getRide(guest.favouriteRide);
  console.log(`Favourite: ${ride.name}`);
}

Financial

cash · number

Amount of cash in the guest’s pocket.

console.log(`Cash: £${guest.cash / 10}`);
guest.cash = 5000; // Give guest £50

Location

isInPark · boolean

Whether the guest is within the park boundaries.

if (guest.isInPark) {
  console.log(`${guest.name} is in the park`);
}

isLost · boolean

Whether the guest is lost (lostCountdown < 90).

if (guest.isLost) {
  console.log(`${guest.name} is lost!`);
}

lostCountdown · number

Countdown (0-255) tracking how long the guest has been looking for their destination.

console.log(`Lost countdown: ${guest.lostCountdown}`);

destination · CoordsXY

The guest’s direct destination coordinates.

console.log(`Heading to: (${guest.destination.x}, ${guest.destination.y})`);

direction · Direction

The guest’s orthogonal direction (0-3).

console.log(`Facing direction: ${guest.direction}`);

Thoughts

thoughts · Thought[]

The list of thoughts this guest has.

guest.thoughts.forEach(thought => {
  console.log(thought.toString());
});

Each thought has:

• type - The thought type (e.g., “sick”, “hungry”, “was_great”)
• item - The thought argument (ride ID, shop item, etc.)
• freshness - How fresh the thought is (lower = more recent)
• freshTimeout - The freshness timeout
• toString() - Get formatted string with Unicode quotes

function analyzeThoughts(guest) {
  const thoughtTypes = {};
  
  guest.thoughts.forEach(thought => {
    thoughtTypes[thought.type] = (thoughtTypes[thought.type] || 0) + 1;
  });
  
  console.log(`${guest.name}'s thoughts:`, thoughtTypes);
}

Items

items · GuestItem[]

The list of items this guest has.

console.log(`${guest.name} has ${guest.items.length} items`);

hasItem()

Checks whether the guest has a certain item.

item · GuestItem · required

The item to check for.

if (guest.hasItem('map')) {
  console.log(`${guest.name} has a map`);
}

if (guest.hasItem('umbrella')) {
  console.log(`${guest.name} has an umbrella`);
}

giveItem()

Gives an item to the guest. Guests can only have one item of each type.

item · GuestItem · required

The item to give.

// Give simple item
guest.giveItem('balloon');
guest.giveItem('map');
guest.giveItem('umbrella');

// Give photo with ride ID
guest.giveItem({
  type: 'photo1',
  rideId: 0
});

// Give voucher
guest.giveItem({
  type: 'voucher',
  voucherType: 'entry_free'
});

removeItem()

Removes an item from the guest’s possession.

item · GuestItem · required

The item to remove.

guest.removeItem('balloon');
guest.removeItem('map');

removeAllItems()

Removes all items from the guest’s possession.

guest.removeAllItems();
console.log('All items removed');

Animations

availableAnimations · GuestAnimation[]

The animations available to this guest.

console.log('Available animations:', guest.availableAnimations);

animation · GuestAnimation

The animation the guest is currently exhibiting. Animations include: “walking”, “checkTime”, “watchRide”, “eatFood”, “shakeHead”, “emptyPockets”, “wow”, “throwUp”, “jump”, “joy”, “readMap”, “wave”, “takePhoto”, “clap”, etc.

console.log(`Current animation: ${guest.animation}`);
guest.animation = 'wave'; // Make guest wave

animationOffset · number

The frame offset in the current animation.

console.log(`Animation frame: ${guest.animationOffset}`);

animationLength · number

The total number of frames in the current animation.

console.log(`Animation length: ${guest.animationLength}`);

getAnimationSpriteIds()

Gets an array of sprite IDs representing a particular guest animation.

animation · GuestAnimation · required

The animation to get sprites for.

rotation · number · required

The rotation (0-7).

const sprites = guest.getAnimationSpriteIds('wave', 0);
console.log('Wave animation sprites:', sprites);

Flags

getFlag()

Gets whether a given flag is set.

key · PeepFlags · required

The flag to test.

if (guest.getFlag('tracking')) {
  console.log(`${guest.name} is being tracked`);
}

if (guest.getFlag('leavingPark')) {
  console.log(`${guest.name} is leaving`);
}

setFlag()

Sets a flag to the given value.

key · PeepFlags · required

The flag to set.

value · boolean · required

Whether to set or clear the flag.

guest.setFlag('tracking', true); // Enable tracking
guest.setFlag('leavingPark', false); // Stop guest from leaving

Available flags: “leavingPark”, “slowWalk”, “tracking”, “waving”, “hasPaidForParkEntry”, “photo”, “painting”, “wow”, “litter”, “lost”, “hunger”, “toilet”, “crowded”, “happiness”, “nausea”, “purple”, “pizza”, “explode”, “rideShouldBeMarkedAsFavourite”, “parkEntranceChosen”, “contagious”, “joy”, “angry”, “iceCream”, “hereWeAre”, “positionFrozen”, “animationFrozen”

Usage Examples

Find Unhappy Guests

function findUnhappyGuests() {
  const guests = map.getAllEntities('guest');
  const unhappy = guests.filter(g => g.happiness < 100);
  
  console.log(`Found ${unhappy.length} unhappy guests`);
  
  unhappy.forEach(guest => {
    console.log(`${guest.name}: Happiness ${guest.happiness}`);
    guest.thoughts.forEach(thought => {
      console.log(`  - ${thought.toString()}`);
    });
  });
}

Guest Status Report

function guestReport(guest) {
  console.log(`=== ${guest.name} ===`);
  console.log(`Location: (${guest.x}, ${guest.y}, ${guest.z})`);
  console.log(`In park: ${guest.isInPark}`);
  console.log(`Cash: £${(guest.cash / 10).toFixed(2)}`);
  console.log(`Happiness: ${guest.happiness}/255`);
  console.log(`Energy: ${guest.energy}`);
  console.log(`Hunger: ${guest.hunger}`);
  console.log(`Thirst: ${guest.thirst}`);
  console.log(`Nausea: ${guest.nausea}`);
  console.log(`Items: ${guest.items.map(i => i.type).join(', ')}`);
}

Give Free Items

function giveFreeItems() {
  const guests = map.getAllEntities('guest');
  
  guests.forEach(guest => {
    if (!guest.hasItem('map')) {
      guest.giveItem('map');
    }
    
    if (climate.current.weather === 'rain' && !guest.hasItem('umbrella')) {
      guest.giveItem('umbrella');
    }
  });
}

Make Everyone Happy

function makeEveryoneHappy() {
  const guests = map.getAllEntities('guest');
  
  guests.forEach(guest => {
    guest.happiness = 255;
    guest.happinessTarget = 255;
    guest.energy = 128;
    guest.hunger = 255;
    guest.thirst = 255;
    guest.nausea = 0;
    guest.toilet = 0;
  });
  
  console.log(`Made ${guests.length} guests happy!`);
}