> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyxeron.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Guests & spending

> How many guests come, who they are, what they pay at the door, and the per-minute rule that decides when a guest buys a token.

Guests are the club's only source of revenue, and every one of them is simulated individually. **Why:** the levers the player pulls (hype, promotions, prices, door policy, staff) should show up as real people who do or do not walk in, pay, and buy.

All random draws below come from the seeded deterministic generator described in [The night loop](/engine/night-loop), so the same seed produces the same crowd.

## How many guests come

When the club opens, the engine computes tonight's expected head count $N$ and generates exactly that many walk-in guests.

$$
N = \operatorname{round}\!\Big( D_L \cdot \big(0.4 + 1.0\,\tfrac{H}{100} + 0.4\,\tfrac{R}{100}\big) \cdot B_d \cdot \Pi \cdot \Sigma \Big)
$$

where

* $D_L$ is the venue's base demand at level $L$ (guests).
* $H \in [0, 100]$ is hype and $R \in [0, 100]$ is reputation.
* $B_d$ is the busy-night bonus: $B_d = 1.25$ if $\operatorname{weekday}(d) = (d - 1) \bmod 7 \in \lbrace 3, 5, 6 \rbrace$ (Wednesday, Friday, Saturday; day 1 is a Sunday), else $1$.
* $\Pi$ is the house-policy multiplier (below).
* $\Sigma$ is the safety multiplier: word gets around, so an unsafe club loses up to a quarter of its walk-ins.

$$
\Sigma = 0.75 + 0.25 \cdot \frac{\text{Safety}}{100}
$$

House policies (Level 3 and up; below that $\Pi = 1$):

$$
\Pi = \big(1 + 0.12\,\mathbb{1}_{\text{ladies}}\big) \cdot \delta_{\text{dress}} \cdot \operatorname{clamp}\!\Big(1 - 0.2\,\frac{c - c_L}{12\, k_L},\; 0.3,\; 1.5\Big)
$$

where $\mathbb{1}_{\text{ladies}}$ is 1 on ladies' night, $\delta_{\text{dress}}$ the dress code's demand factor (1, 0.95, 0.85 for none, smart, strict), $c$ the cover the player set, $c_L$ the venue's standard cover and $k_L$ the venue's price scale. A cover above standard thins the crowd; a cheaper one pulls more in.

A sealed venue (after a failed inspection) generates $N = 0$.

| Level | Venue | Base demand $D_L$ | Capacity | Standard cover $c_L$ | Price scale $k_L$ | Stay (min) |
| - | - | - | - | - | - | - |
| 1 | Token Booth | 260 | 20 | 0 | 1.5 | 20–60 |
| 2 | Token Shop | 260 | 40 | 0 | 4 | 20–60 |
| 3 | Token Bar & Live Music | 300 | 90 | 0 | 12 | 45–150 |
| 4 | Nightclub | 160 | 190 | 600 | 48 | 60–240 |
| 5 | Premium Venue | 600 | 500 | 2500 | 60 | 60–240 |

| Parameter | Value |
| - | - |
| Base demand factor | 0.4 |
| Hype weight | 1.0 |
| Reputation weight | 0.4 |
| Busy weekdays | 3, 5, 6 |
| Busy bonus | 1.25 |
| Safety demand floor | 0.75 |
| Ladies' night demand bonus | 0.12 |
| Cover elasticity / reference | 0.2 / 12 |

## Who each guest is

Each guest is drawn independently.

**Segment.** The audience is a weighted mix of five segments. Every active promotion adds weight to the segment its channel reaches, and a dress code attracts big spenders:

$$
\Pr(\text{segment} = s) = \frac{w_s}{\sum_j w_j}, \qquad
w_s = w^0_s + 2 \cdot \#\lbrace \text{active promos targeting } s \rbrace + \mathbb{1}_{s = \text{premium}} \cdot \pi_{\text{dress}}
$$

where $w^0_s$ is the base weight and $\pi_{\text{dress}}$ is 0, 1 or 2.

| Segment | Base weight $w^0_s$ | Budget range | Genres | Promoted by |
| - | - | - | - | - |
| locals | 3 | 40–120 | hiphop, rnb | Posters (500 coin, +4 hype) |
| community | 2 | 60–150 | house, techno | X (800, +6) |
| urban25 | 2 | 100–250 | house, rnb, edm | Instagram (1500, +10) |
| genZ | 2 | 50–140 | edm, hiphop | TikTok (2000, +14) |
| premium | 1 | 250–600 | techno, house | Influencer (5000, +25) |

A promotion therefore works twice: it adds hype (more guests) and tilts the mix toward its audience.

**Gender.** A guest is a woman with probability

$$
\varphi = 0.42 + 0.14\,\mathbb{1}_{\text{ladies}}
$$

**Music taste.** With probability 0.4 the guest likes the club's own genre; otherwise a genre is picked uniformly from the segment's list.

**Budget.** The cash a guest brings, in coin:

$$
b_0 = \operatorname{round}\!\Big( U\lbrace \beta^{\text{lo}}_s, \dots, \beta^{\text{hi}}_s \rbrace \cdot k_L \cdot m_{\text{dress}} \cdot \operatorname{clamp}\!\Big(1 + 0.15\,\frac{c - c_L}{12\,k_L},\; 0.8,\; 1.3\Big) \cdot \mu_g \Big)
$$

$$
\mu_g = \begin{cases}
1 & \text{woman} \\
1 + 0.5\,(\varphi - 0.42) + \min(0.3,\; 0.05\, n_{\text{host}}) & \text{man}
\end{cases}
$$

where $U\lbrace\cdot\rbrace$ is a uniform integer draw from the segment's budget range, $m_{\text{dress}}$ the dress-code budget multiplier (1, 1.2, 1.4), and $n_{\text{host}}$ the hosts on shift. An expensive door brings bigger spenders; men spend more in a room with more women and with hosts working it.

**Arrival and stay.** Arrival minute $\alpha \sim U\lbrace 0, \dots, 239 \rbrace$. Leave minute $\lambda = \alpha + U\lbrace \text{stay}^{\text{lo}}_L, \dots, \text{stay}^{\text{hi}}_L \rbrace$. Every guest starts with satisfaction 60, tilt 0, and is underage with probability 0.05.

### Promoters and happy hour

A booked promoter brings a guest list of $U\lbrace \operatorname{round}(0.8h), \dots, \operatorname{round}(1.2h) \rbrace$ heads, all from one segment, arriving in the first 75 minutes. They get in free and the promoter is paid a commission per head admitted.

| Promoter | Segment | Heads $h$ | Commission per head |
| - | - | - | - |
| Campus Crew | genZ | 30 | 60 |
| Social Circle | urban25 | 20 | 100 |
| Elite List | premium | 12 | 250 |

A scheduled **early** happy hour moves each guest who would arrive at minute 60 or later to a uniform minute in the first hour with probability 0.25. A **late** happy hour extends by 30 minutes (capped at closing) the stay of every guest due to leave between minute 240 and 359.

### Extra guests from a night-time promo

Posting a promo after the doors open pulls in extra guests over the rest of the night, fewer the later it is:

$$
N_{\text{extra}} = \operatorname{round}\!\Big( D_L \cdot 1.0 \cdot \frac{\Delta H}{100} \cdot B_d \cdot \operatorname{clamp}\!\Big(\frac{300 - t}{300},\, 0,\, 1\Big) \Big)
$$

where $\Delta H$ is the hype the promo actually added (after the 0–100 clamp), $t$ the current minute, and 300 the last arrival minute (360 minus a 60-minute late-arrival cutoff). Each extra guest arrives at a uniform minute between $t + 1$ and 300. These guests are appended to the end of tonight's guest list rather than merged into arrival order, so they are processed after everyone drawn when the club opened.

## The door

Each minute, guests whose arrival minute has come join the queue. The door then processes at most **3** queued guests, in arrival order:

1. **Capacity.** If the number inside has reached $C = \operatorname{round}\big(\text{capacity}_L \cdot (1 + 0.15\, u_{\text{cap}})\big)$, the door closes for this minute, unless the player forced it open (a violation under R10). Here $u_{\text{cap}} \in \lbrace 0, 1, 2, 3 \rbrace$ is the capacity upgrade tier.
2. **ID check.** An underage guest is turned away if the club has security, or if it is below Level 3 (the owner checks IDs at the counter). Otherwise the guest gets in, and an inspector who visits that night will find them.
3. **Dress code.** Turned away with probability 0.1 / 0.25 (men) or 0.03 / 0.08 (women) under a smart / strict code.
4. **Cover.** If the guest's budget $b$ is below the cover $c_g$, they go home: the door never takes a whole wallet. Otherwise they pay $c_g$ and their budget drops by it. Here $c_g = 0$ for guest-list guests and for women on ladies' night, and $c_g = c$ otherwise.

Turned-away guests still use up one of the 3 door slots that minute.

## When a guest buys

Every minute, each guest inside picks one token from the menu at random and decides whether to go to the bar. **Why:** demand should respond smoothly to price, to the room's mood and to the market, without the player having to micromanage individuals.

**The price.** The player sets a list price $p_k$ per token. During happy hour the list drops to $\ell_k = \max(1, \operatorname{round}(0.5\,p_k))$, otherwise $\ell_k = p_k$. Guests pay the list times the live market multiplier $\mu_{k,t}$:

$$
\pi_{k,t} = \max\!\big(1,\; \operatorname{round}(\ell_k \cdot \mu_{k,t})\big)
$$

**The reference price.** Each token has a standard price for the venue, which follows the real-world spot price of its underlying stocks:

$$
\bar p_k = \max\!\big(1,\; \operatorname{round}(\operatorname{round}(p^0_k\, k_L) \cdot \chi_k)\big)
$$

where $p^0_k$ is the token's default price and $\chi_k \in [0.2, 5]$ the spot factor (current spot over the spot when the club first saw it, weighted over the token's legs; 1 when offline).

**The bar probability.** A guest with tilt $\tau$ goes for token $k$ with probability

$$
q_{g,k,t} = \beta_t \cdot 0.06 \cdot \min\!\Big(1.5,\; \frac{\bar p_k}{\ell_k}\Big) \cdot F_{k,t} \cdot \max\!\Big(0.2,\; 1 - \frac{\tau}{150}\Big)
$$

| Factor | Meaning |
| - | - |
| $0.06$ | Base bar chance per minute |
| $\min(1.5, \bar p_k / \ell_k)$ | **Price sensitivity.** 1 at the reference price, halves when the list is doubled, capped at 1.5 for prices at or below two-thirds of reference |
| $F_{k,t}$ | **FOMO.** A token rising above its recent average draws buyers (below) |
| $\max(0.2, 1 - \tau / 150)$ | Tilted guests slow down, never below 20% |
| $\beta_t$ | Room boost: $\beta_t = \operatorname{lerp}(0.8, 1.25;\, E_t / 100) \cdot (1 + 0.15\,\kappa_t)$ at Level 3 and up, $1 \cdot (1 + 0.15\,\kappa_t)$ below; $\beta_t = 0$ for a guest who already hit an out-of-stock token when nothing is left in stock |

Here $E_t$ is crowd energy and $\kappa_t = \min(1, 60\, n_{\text{rel}} / \text{inside})$ the share of guests covered by Guest Relations staff (see [Crowd, DJ & security](/engine/crowd)).

**One draw decides.** The engine draws a single $u \sim U[0, 1)$ per guest and minute, and with $\delta_t = 0.5 \cdot \operatorname{lerp}(0.6, 1.4;\, E_t/100)$ the dance chance:

$$
\text{action} = \begin{cases}
\text{buy } k & u \lt q \text{ and } b \ge \pi_{k,t} \text{ and a bar slot is free} \\
\text{wait at the bar } (-1 \text{ satisfaction}) & u \lt q \text{ and } b \ge \pi_{k,t} \text{ and no slot is free} \\
\text{dance} & u \lt q + \delta_t \text{ otherwise} \\
\text{idle } (-0.05 \text{ satisfaction}) & \text{else}
\end{cases}
$$

So a guest who can afford the token buys with probability $q$ and dances with probability $\delta_t$; a guest who cannot afford it dances with probability $q + \delta_t$. Below Level 3 the energy factors are 1 and $\delta_t = 0.5$.

**Bar throughput.** The bar serves at most $2\,(1 + n_{\text{bartender}})$ orders per minute. Guests are served in arrival order; once the slots run out, the rest wait and lose satisfaction.

### What a sale does

If the token is out of stock, the guest is disappointed (satisfaction $-10$) and from then on only orders tokens that are in stock. Otherwise:

$$
\begin{aligned}
b &\leftarrow b - \pi_{k,t} \\
\text{coin} &\leftarrow \text{coin} + \pi_{k,t} - \operatorname{round}\!\big(0.05 \cdot \max(0,\; \pi_{k,t} - c^{\text{buy}}_k\, k_L\, \chi_k)\big) \\
\tau &\leftarrow \tau + \text{fomo}_k \\
\text{sat} &\leftarrow \text{sat} + 5
\end{aligned}
$$

where $c^{\text{buy}}_k$ is the token's buy cost and 0.05 the platform's share of the spread over spot. The stock of $k$ drops by one.

**Buying a round.** Right after a purchase, a man who can still afford it buys a second unit (if a bar slot is free) with probability

$$
\rho_t = \min\!\big(0.55,\; 0.08 + 0.4\, f_t + 0.02\, n_{\text{host}}\big)
$$

where $f_t$ is the share of women among guests inside. The round adds +2 satisfaction.

### Spend per guest

There is no fixed spend-per-guest constant. A guest's spend is whatever the per-minute rule produces until the night ends or they leave, bounded by their budget:

$$
\text{spend}_g = c_g + \sum_{\text{purchases}} \pi_{k,t} \;\le\; b_0 \qquad (c_g \le b_0 \text{ for every guest let in})
$$

The one exception is the sparkler parade (see [Crowd, DJ & security](/engine/crowd)). A guest whose remaining budget covers a bottle at $\operatorname{round}(0.35\, m_{\text{table}})$ may copy the parade and buy one; the club books the full bottle price as table revenue, but only 40% of it comes out of the guest's budget (the other 60% is an impulse splurge). Sparkler bottles therefore let a guest's total spend exceed $b_0$.

Over a stretch of minutes where the guest can afford the tokens and the bar has slots, the expected number of purchases per minute is $\frac{1}{\lvert M \rvert} \sum_{k \in M} q_{g,k,t}$ plus rounds, with $M$ the tokens unlocked at this level.

| Token | Default price $p^0_k$ | Buy cost $c^{\text{buy}}_k$ | Tilt per buy | Volatility $v_k$ | Unlocks at level |
| - | - | - | - | - | - |
| Tesla (tsla) | 25 | 6 | 10 | 0.012 | 1 |
| US Broad Market (us500) | 15 | 3 | 0 | 0.004 | 1 |
| NVIDIA (nvda) | 40 | 10 | 18 | 0.011 | 2 |
| Big Tech (bigtech) | 55 | 13 | 18 | 0.007 | 2 |
| AI Semis (aisemis) | 50 | 12 | 14 | 0.009 | 3 |
| Dividend Blue Chips (dividend) | 60 | 15 | 12 | 0.005 | 3 |
| SK Hynix (skhy) | 58 | 14 | 16 | 0.013 | 4 |
| SpaceX (spcx) | 90 | 20 | 22 | 0.018 | 5 |

## The token market inside the club

Each token trades at a multiplier $\mu_{k,t}$ on its list price, starting at 1. **Why:** the party moves the market, and the market moves the guests. Every minute:

$$
\mu_{k,t+1} = \operatorname{clamp}\!\Big( \mu_{k,t} \cdot \exp\!\big( \underbrace{0.002\,\tfrac{E_t - 50}{50} - 0.015\,(\mu_{k,t} - 1) + P_t}_{\text{drift}} + \underbrace{1.7\,v_k\,(2u - 1)}_{\text{shock}} \big),\; 0.4,\; 3 \Big)
$$

where $v_k$ is the token's volatility, $u \sim U[0, 1)$, and the pump $P_t$ is 0.06 in the minute the DJ takes the decks plus 0.004 per minute while the DJ's anthem plays. A slow average follows the price, $\bar\mu_{k,t+1} = \bar\mu_{k,t} + 0.05\,(\mu_{k,t+1} - \bar\mu_{k,t})$, and drives FOMO:

$$
F_{k,t} = \operatorname{clamp}\!\Big(1 + 3\Big(\frac{\mu_{k,t}}{\bar\mu_{k,t}} - 1\Big),\; 0.75,\; 1.4\Big)
$$

Guests also feel their own paper profit. Each buyer keeps a cost basis $\theta_g$, the running mean of the menu-wide index $I_t = \frac{1}{\lvert M \rvert}\sum_{k} \mu_{k,t}$ at their purchases. Each minute, with $\text{pnl} = I_t / \theta_g - 1$:

$$
\text{sat} \leftarrow \text{sat} + 0.6\,\text{pnl}, \qquad \tau \leftarrow \tau + 8\,\max(0,\, -\text{pnl})
$$

Losing guests get tilted, and tilted guests buy less and start fights (see [Crowd, DJ & security](/engine/crowd)).

| Parameter | Value |
| - | - |
| Energy drift | 0.002 |
| Mean reversion | 0.015 |
| DJ start pump | 0.06 |
| Anthem pump | 0.004 / min |
| Average follow rate | 0.05 |
| Momentum | 3 |
| FOMO range | 0.75–1.4 |
| Multiplier range | 0.4–3 |
| P\&L to satisfaction / tilt | 0.6 / 8 |

## Reserved tables

At minute 90 the tables booked by Guest Relations arrive and pay their minimum spend in one go. Bookings per seat type $s$ are fixed when the club opens:

$$
n_s = \min\!\Big(\text{seats}_s,\; \operatorname{round}\big(\text{demand}_s \cdot \operatorname{clamp}\big(1 - e_s\,(\tfrac{m_s}{\bar m_s} - 1),\, 0,\, 1.5\big)\big)\Big)
$$

$$
\text{demand}_s = \begin{cases}
\text{seats}_s \cdot (0.3 + R / 200) & \text{bar seats (walk-ins)} \\
n_{\text{rel}} \cdot 1.5 \cdot (0.5 + R/100) & \text{VIP, sofa, table}
\end{cases}
$$

where $m_s$ is the player's minimum spend, $\bar m_s = \operatorname{round}(m^0_s\, k_L)$ the standard one ($m^0_s$ = 750, 300, 200, 60 for VIP, sofa, table, bar) and $e_s$ the elasticity (0.5, or 0.7 for bar seats). Table revenue is $\sum_s n_s\, m_s$.

## Players as guests

In multiplayer, a human visitor walks in while the club is open (the night, before 04:00, not sealed after a failed inspection) by paying the club's cover from their own wallet (no entry if it can't cover it) and buys at the list price times the live market multiplier, $\max(1, \operatorname{round}(p_k\, \mu_{k,t}))$, decreasing the club's stock exactly like a simulated guest. Player visitors always pay full price: the happy-hour discount and free entry (guest lists, women on ladies' night) apply only to simulated guests. What they buy goes home with them; the club never buys back.

<Accordion title="Worked example: a Saturday at the Nightclub (Level 4)">
  Day 7 (weekday 6, Saturday), hype $H = 40$, reputation $R = 60$, safety 100, no house policies, no promos.

  **Head count.** $N = \operatorname{round}\big(160 \cdot (0.4 + 0.40 + 0.24) \cdot 1.25 \cdot 1 \cdot 1\big) = \operatorname{round}(208) = 208$ walk-ins, against a capacity of 190. Late arrivals will queue at a full door.

  **A guest.** An urban25 man draws a base budget of 150, so $b_0 = 150 \times 48 = 7200$ coin. He pays the standard cover of 600 and enters with 6600.

  **His first minute at the bar.** He picks Tesla. The reference is $\bar p = \operatorname{round}(25 \times 48) = 1200$ (spot factor 1). The player has priced it at $\ell = 1500$; the market is flat ($\mu = 1$, $F = 1$), energy is 50, no Guest Relations, tilt 0:

  $$
  \beta = 0.8 + 0.45 \times 0.5 = 1.025, \qquad
  q = 1.025 \times 0.06 \times \min\!\big(1.5, \tfrac{1200}{1500}\big) \times 1 \times 1 = 0.0492
  $$

  That is about 4.9% per minute, or roughly 3 purchases an hour if every token were priced like this. Priced at the reference instead, $q$ rises to 0.0615 (+25%), but each sale brings in 1200 rather than 1500.
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.