StartDiceMatch

Starts a match of the game’s dice game between two players - the heart of a dice command.

The two must stand together at a dice table (within range metres of each other; the games look for the table nearest the challenger), in the world, alive, on foot, not fighting, not at a shop and not playing already, and both must have the stake in their purse. The stake leaves both purses at once and goes to the winner at the end. When it cannot start, the second value says why in words the player can read (“Hans is too far away - stand together at a dice table.”, “Henry cannot cover the bet of 50 Groschen.” …), ready for the chat. A game type with badges or a rule out of its bounds is refused the same way, with a reason meant for you (“The turn timeout must be 5 to 3600 seconds.”).

Syntax

StartDiceMatch(challenger, opponent, bet, gameType, turnTimeout, range)

Parameter	Type
challenger	number	the player who asks - they throw first
opponent	number	the other player
bet	number	each player’s stake in Groschen; 0 or nil for none
gameType	number	0 beggar (1500 points, the default), 1 wagoner (2000), 5 craftsman (3000), 9 courtier (4000)
turnTimeout	number	seconds a player may take for one move before losing the match; nil for 90 (5 to 3600)
range	number	metres the two may stand apart when the match starts; nil for 4 (0.5 to 8)

Returns

the match id, or nil, reason - the reason as the player reads it

Example

-- /dice <name> [bet] asks, /dice accept answers (the shipped modes' command, shortened), with this server's rules
local DICE = {game_type = 5, turn_timeout = 60, range = 3}   -- the craftsman's game, a minute a move
local challenges = {}
function OnPlayerCommandText(pid, cmd, args)
  if cmd ~= "dice" then return false end
  local word, rest = args:match("^(%S*)%s*(.-)$")
  if word == "accept" then
    local c = challenges[pid]
    challenges[pid] = nil
    if not c then SendClientMessage(pid, COLOR_RED, "Nobody challenged you.") return true end
    local id, why = StartDiceMatch(c.from, pid, c.bet, DICE.game_type, DICE.turn_timeout, DICE.range)
    if not id then SendClientMessage(pid, COLOR_RED, why) SendClientMessage(c.from, COLOR_RED, why) end
  else
    local target = GetPlayerId(word)
    if not target then SendClientMessage(pid, COLOR_RED, "No such player.") return true end
    challenges[target] = {from = pid, bet = tonumber(rest) or 0}
    SendClientMessage(target, COLOR_SERVER, GetPlayerName(pid) .. " challenges you to dice - /dice accept")
  end
  return true
end

See also

OnDiceMatchStart · OnDiceMatchEnd · EndDiceMatch · GetPlayerDiceMatch · the Dice group of the index