API Reference

API Reference

This page is organized by the task you are trying to perform. The normal setup is: create a table, configure it, start player sessions, then observe results through events.

Quick start

new tableid = ShellGame_CreateTable(1465.75, -1661.73, 13.45, 90.0);
if (tableid == INVALID_SHELLGAME_TABLE)
{
    return 0;
}

ShellGame_SetTableEconomy(tableid, 100, 2.0);
ShellGame_SetTableLevels(tableid, 1, SHELLGAME_UNLIMITED);
// The default is one active player per table.
ShellGame_SetTableCapacity(tableid, 1);

Separate tables can run at the same time. Capacity is per table. It does not limit the server globally.

Tables

Create a table

ShellGame_CreateTable(x, y, z, angle, worldid, interiorid, radius, createDealer, streamDistance, drawDistance) returns a table ID or INVALID_SHELLGAME_TABLE.

Parameter	Meaning	Default
x, y, z	Table centre.	Required
angle	Z rotation in degrees. The same orientation is applied to table geometry, shell positions, selector, ball, and dealer placement.	90.0
worldid, interiorid	Streaming dimension.	0, -1
radius	Interaction radius.	3.0
createDealer	Whether to create the cosmetic dealer actor.	true
streamDistance, drawDistance	Streamer distances for the scene.	200.0, 200.0

The table angle is set during creation.

Remove tables

Function	Use	Return value
ShellGame_DestroyTable(tableid)	Remove one table and clean up its sessions and entities.	true when destroyed. A live stake is voided first.
ShellGame_DestroyAllTables()	Gamemode-shutdown cleanup.	Number of tables destroyed.

Configure a table

Goal	Function	Notes
Economy	ShellGame_SetTableEconomy(tableid, baseStake, Float:payoutMultiplier)	Sets the default stake base and win multiplier.
Level range	ShellGame_SetTableLevels(tableid, startLevel, maxLevel = 0)	maxLevel = 0 means unlimited.
Same-table concurrency	ShellGame_SetTableCapacity(tableid, capacity = 0)	The shipped default is 1. 0 means unlimited for this table.
Shuffle difficulty	ShellGame_SetTableDifficulty(tableid, baseShuffles, shufflesPerLevel, maxShuffles, baseSwapMs, minSwapMs, Float:speedPerLevel)	maxShuffles = 0 uses only the compile-time safety cap.
Phase timings	ShellGame_SetTableTimings(tableid, previewMs, lowerMs, swapPauseMs, choiceMs, revealMs, betweenRoundsMs)	Times are milliseconds. choiceMs and betweenRoundsMs must be positive.
Fake movements	ShellGame_SetTableFakeChance(tableid, percent)	Accepts 0 through 100. 0 disables feints.

All setters return false for an invalid table or invalid values.

Inspect a table

Function	Returns
ShellGame_IsValidTable(tableid)	Whether the table ID is live.
ShellGame_GetTableCount()	Number of live tables.
ShellGame_GetTableActivePlayers(tableid)	Active sessions on the table.
ShellGame_GetTableMaxLevel(tableid)	Maximum level, or 0 when unlimited.
ShellGame_GetTableFakeChance(tableid)	Fake-movement percentage, or -1 for an invalid table.
ShellGame_GetTablePosition(tableid, &Float:x, &Float:y, &Float:z, &Float:angle)	Writes the table centre and angle, then returns success.

Player sessions

Start and control play

Function	Use	Important behavior
ShellGame_Start(playerid, tableid, requireProximity = true)	Start the normal round at the table's configured starting level.	Charges the current quote and returns true only when the scene is ready.
ShellGame_StartAtLevel(playerid, tableid, level, requireProximity = true)	Trusted admin/testing start at a specific level.	Charges that level's real stake. It does not simulate skipped levels.
ShellGame_Select(playerid, E_SHELLGAME_SLOT:slot)	Lock a selection during the selecting phase.	Returns false outside selection or for an invalid slot.
ShellGame_Continue(playerid)	Start the next level after a win.	Requires a valid next-round quote.
ShellGame_Stop(playerid)	Stop between rounds or forfeit an unresolved paid round.	Refuses after the result is immutable.
ShellGame_Void(playerid)	Abort because trusted gamemode code detected a failure.	Refunds a live stake. Do not expose it as a player cancel command.

The normal manual-control flow is:

ShellGame_Start(playerid, tableid);
ShellGame_Select(playerid, SHELLGAME_SLOT_LEFT);
ShellGame_Continue(playerid); // after a win, if desired
ShellGame_Stop(playerid);

requireProximity = false skips only the small interaction-radius check. The player must still be in the table's supported dimension and stream distance.

Read player state

Use ShellGame_GetPlayerState(playerid) to decide which action is valid. Do not infer the session phase from position or camera state.

Function	Returns
ShellGame_GetPlayerState(playerid)	E_SHELLGAME_STATE, or SHELLGAME_STATE_NONE when inactive.
ShellGame_GetPlayerTable(playerid)	Current table ID, or INVALID_SHELLGAME_TABLE.
ShellGame_GetPlayerNearbyTable(playerid)	Table associated with the interaction prompt, or invalid.
ShellGame_GetPlayerLevel(playerid)	Current level.
ShellGame_GetPlayerStake(playerid)	Current or next-round stake.
ShellGame_GetPlayerPotentialReturn(playerid)	Quoted win return.
ShellGame_GetPlayerNet(playerid)	Logical net result for the current run.
ShellGame_GetPlayerChoiceResponse(playerid)	Server-measured choice response time in milliseconds.
ShellGame_GetPlayerSelectorMoves(playerid)	Accepted left/right selector movements.
ShellGame_IsPlayerAtTable(playerid, tableid)	Whether the player is in the table dimension and radius.

The available slot values are SHELLGAME_SLOT_LEFT, SHELLGAME_SLOT_CENTRE, SHELLGAME_SLOT_CENTER, and SHELLGAME_SLOT_RIGHT. INVALID_SHELLGAME_SLOT represents no selection, such as a timeout.

Economy integration

Without overrides, the include uses GTA money. Custom economies have two separate responsibilities: calculating/checking a stake, and committing debits or credits.

Calculate and check stakes

Callback	Purpose	Return value
OnShellGameGetStake(playerid, tableid, level)	Calculate the stake for a level.	A non-negative amount. Negative values become zero.
OnShellGameCanPay(playerid, tableid, amount)	Check funds before payment.	Non-zero when the player can pay.

Commit money changes

If any ledger callback is supplied, all three are required:

Callback	Operation
OnShellGamePay(playerid, tableid, amount)	Atomically debit a stake.
OnShellGamePayout(playerid, tableid, amount)	Atomically credit a win.
OnShellGameRefund(playerid, tableid, amount)	Atomically credit a refund or void.

Return non-zero only after the complete transaction succeeds. A failed payment must not debit anything. The payout multiplier is fixed when the round is paid, so later table changes cannot change its advertised return.

Recover failed credits

If a payout or refund cannot be completed immediately, the include calls OnShellGameTransactionFailed(playerid, tableid, transaction, amount). Return non-zero only after settling the credit or durably storing the obligation against the player's account. Returning zero leaves it pending and blocks another run for that player.

Function	Use
ShellGame_HasPendingTransaction(playerid)	Check for an unsettled credit.
ShellGame_GetPendingTransactionType(playerid)	Read payout vs. refund.
ShellGame_GetPendingTransactionTable(playerid)	Read the originating table.
ShellGame_GetPendingTransactionAmount(playerid)	Read the amount still owed.
ShellGame_AcknowledgePendingTransaction(playerid)	Clear the local marker after external settlement.

Only acknowledge after the obligation has actually been settled or persisted. Because player IDs can be reused, persist account-level failures during disconnect handling rather than relying on the slot-local pending state.

Events

All event callbacks are optional and already forwarded by the include. Use them for UI, logging, analytics, and account integration. Use the player API for actions.

Table and area lifecycle

Callback	Fires when
OnShellGameTableCreated(tableid)	A table has been created and registered.
OnShellGameTableDestroyed(tableid)	Table cleanup has completed.
OnShellGameEnterArea(playerid, tableid)	A player enters the interaction area.
OnShellGameLeaveArea(playerid, tableid)	A player leaves the interaction area.

Round progress

Callback	Fires when	Important data
OnShellGameRoundStart(playerid, tableid, level, stake)	A paid round begins.	Charged stake and level.
OnShellGameShuffleComplete(playerid, tableid, level)	Shuffling finishes.	The player may now choose.
OnShellGameChoiceLocked(playerid, tableid, level, selectedSlot, responseMs, selectorMoves)	A choice is confirmed or times out.	Timeout uses INVALID_SHELLGAME_SLOT. The ball slot is intentionally hidden here.
OnShellGameResult(playerid, tableid, level, selectedSlot, ballSlot, result, stake, returnAmount)	The immutable result is settled.	Result, correct slot, stake, and credited return.
OnShellGameLevelUp(playerid, tableid, newLevel)	A win advances the player.	The next level before its stake is charged.

Session end

OnShellGameEnd(playerid, tableid, E_SHELLGAME_END_REASON:reason, level, totalNet) fires when a session ends. reason identifies completion, stop, forfeit, disconnect, table destruction, void, or internal failure. totalNet is the run's logical result after stakes and owed credits.

Event callbacks are observational. Defer start, stop, void, and table-destruction actions until after the callback returns. OnShellGameChoiceLocked fires exactly once when the choice becomes immutable, including timeout.

Compile-time options

Define options before #include <shellgame>:

#define SHELLGAME_MAX_TABLES                 (50)
#define SHELLGAME_MAX_SHUFFLES               (128)
#define SHELLGAME_TICK_MS                    (25)
#define SHELLGAME_DEFAULT_CAPACITY           (1)
#define SHELLGAME_CURRENCY_PREFIX            "tokens "

#define SHELLGAME_DISABLE_DEFAULT_CONTROLS
#define SHELLGAME_DISABLE_DEFAULT_UI
#define SHELLGAME_DISABLE_DEFAULT_SOUNDS
#define SHELLGAME_DISABLE_DEFAULT_SHUFFLE_ANIMATIONS
#define SHELLGAME_DISABLE_DEFAULT_EXIT_ANIMATIONS
#define SHELLGAME_DISABLE_DEFAULT_PRESENTATION

SHELLGAME_DISABLE_DEFAULT_SHUFFLE_ANIMATIONS disables the dealer's shuffle animation; it does not enable a player shuffle animation. Players remain still during shuffling by default. SHELLGAME_DISABLE_DEFAULT_EXIT_ANIMATIONS also disables the player's exit animation and the dealer's exit animation.

The include also exposes SHELLGAME_* defaults for models, colours, sounds, animations, timings, distances, economy, difficulty, fake movements, and dealer placement. Define a value before including the file to change the default for subsequently created tables.

Documentation note: This documentation was prepared with assistance from an LLM and manually reviewed. Mistakes can still happen. If you find an error, please open an issue in the repository with the relevant page and suggested correction.