WhitelistEntry¶

The WhitelistEntry table maintains the cluster-wide player whitelist. When whitelisting is enabled on a server (via the whitelist_enabled flag in ServerConfig), only players with a corresponding row in this table are permitted to connect.

Scope¶

🌍 Global — The whitelist is shared across all servers in the cluster. All game hooks subscribe to the full table. A single whitelist addition grants access to every server that has whitelisting enabled.

Schema¶

Column	Type	Constraints	Description
`entry_id`	`u64`	Primary Key, auto-increment	Unique identifier for this whitelist entry
`player_id`	`String`	Unique	Platform-wide player identifier
`added_by`	`String`	—	Identifier of the admin who added the player
`added_at`	`Timestamp`	—	When the player was added to the whitelist

Rust Definition¶

#[spacetimedb::table(public, name = whitelist_entry)]
pub struct WhitelistEntry {
    #[primary_key]
    #[auto_inc]
    pub entry_id: u64,
    #[unique]
    pub player_id: String,
    pub added_by: String,
    pub added_at: Timestamp,
}

Usage Patterns¶

Whitelist Enforcement¶

Whitelist enforcement is a two-step check performed by the game hook during player connection:

Is whitelisting enabled? Check the subscribed ServerConfig row for whitelist_enabled == true.
Is the player whitelisted? Query the subscribed WhitelistEntry data for a matching player_id.

// Pseudocode — game hook whitelist check
fn can_player_connect(player_id: &str, server_config: &ServerConfig) -> bool {
    if !server_config.whitelist_enabled {
        return true; // Whitelist not active — allow all
    }
    WhitelistEntry::filter_by_player_id(player_id).is_some()
}

Unique Constraint¶

The unique constraint on player_id ensures that each player can appear at most once in the whitelist. Attempting to add a player who is already whitelisted will result in a constraint violation. The admin_whitelist_add reducer should check for existence before inserting.

Removal¶

Unlike BanEntry, whitelist entries use hard deletion. When a player is removed from the whitelist, the row is physically deleted from the table. There is no soft-delete or revocation model — whitelist membership is binary.

Relationship with Bans¶

Whitelisting and banning are independent systems. A player can be simultaneously whitelisted and banned. In this case, the ban takes precedence — the game hook should check bans before checking the whitelist:

Player connects
  → Is player banned? → YES → Reject (ban takes priority)
  → Is whitelist enabled? → NO → Allow
  → Is player whitelisted? → NO → Reject
  → Allow

Reducer	Operation
`admin_whitelist_add`	Inserts a new `WhitelistEntry` row
`admin_whitelist_remove`	Deletes the `WhitelistEntry` row for a player
`panel_toggle_whitelist`	Toggles `whitelist_enabled` in ServerConfig (does not modify this table)

Subscriber	Query	Purpose
Game Hook	`SELECT * FROM whitelist_entry`	Real-time whitelist enforcement
Admin Panel	`SELECT * FROM whitelist_entry`	Whitelist management UI

For full subscription architecture, see Subscriptions.

ServerConfig — Contains the whitelist_enabled toggle
BanEntry — Complementary access control (bans override whitelist)
Reducers — admin_whitelist_add and admin_whitelist_remove