Multiplayer Minigame API

From Blue Mars Developer Guidebook

Jump to: navigation, search
There are security restrictions on this article

Contents

Concept

Supervisor Entity

Image:Mp-minigame-put-supervisor-on-level.png

Image:Mp-minigame-spawning.png

Supervisor entity generates (spawns) game master and game player entity on demand. So you need to just put the supervisor entity on a level.

Game Master and Player

Image:Mp-minigame-master-player.png

You can define game master and player entity class. On each client joining a minigame, a player entity is generated and start running. And on only one client, a game master entity is generated. This client is called game owner or game master.

Game master can manage all game state transition. Then each player's state is synchronized by the game master.

Game states are represented as "States" of a CryENGINE's entity system. So you can define the game state transition by the same way as other entity scripts.

Player Status Table

Game master have a table to store each players status. This table is called PlayerStatus. Each players can update values in the player's row.

Shared Data Table

The SharedData table is a table which is shared by all players. Each player can read all keys and values contained in this table. Only game master can update or add values to the SharedData table.

Supervisor

The minigame supervisor can generate and manage the game master and game player entity. In these entity, you can define the rules of the minigame.

Defining Supervisor

ARMPMiniGameSampleSupervisor = {
  Properties = {
    sMasterEntityClass = "ARMPMiniGameSampleMaster",
    sPlayerEntityClass = "ARMPMiniGameSample",
    sSinglePlayerEntityClass = "",
    sGameClass = "AR:Example",
    sGameMenuMovie = "http://xxx.xxx.xxx.xxx/bluemars/bin/RAGolfMatchMaking.swf",
    bAutoStart = 1,
  },

  Editor = {
    Icon = "AR_Default.bmp",
  },
}

ARMiniGameSupervisorBase.Setup (ARMPMiniGameSampleSupervisor)


Note: the Supervisor Base defines an OnInit callback (which uses MMO:RegisterStartCallback to register the GameStart() function, if bAutoStart property is true). So, if you need initialization code in your supervisor, use OnSpawn instead of OnInit, as in the Bowling example.


Flow Nodes

Image:Mp-minigame-flownodes.png

Start

Start the minigame. Calls the GameStart() function.

Exit

Terminate the minigame and exit. Calls the Exit() function.

Overriding Methods

By default, the supervisor generates (spawns) an instance of a entity class which is specified by sMasterEntityClass or sPlayerEntityClass for game master and game player respectively. You can change this behavior by overriding some methods defined in ARMiniGameSupervisorBase table.

Spawning a Single-player Game Entity

Image:Mp-minigame-single-player.png

Game Entities API

Player Status Table

Image:Mp-minigame-playerstatus.png

The game master have a table structure of player status data. Each player can set some value of a particular key in the players row.

For example, to change the value of "CurrentPosition", you can describe your player script like this:

self:UpdateStatus ("CurrentPosition", pos)

Then, the value will be stored on the PlayerStatus table on the game master. The game master always can refer this table. But this data is not delivered to each players.

You can store any type of data such as number, string, boolean and table.

Shared Table

Image:Mp-minigame-shareddata.png

Game Master

Methods

GetPlayerStatus
self:GetPlayerStatus(player_number)

Returns a table of the specified player data from PlayerStatus table.

player_number is a number (1, 2, 3, ...) which specifies a player.

GetPlayerCount
self:GetPlayerCount ()

Returns a total number of players in the minigame.

SendEvent
self:SendEvent {eventType = data [, eventType = data [, ...]]}

eventType can be one of following: updateSharedData, newState

updateStateData modifies the SharedData table. In following example, game master changes the value of "shootCount" on the SharedData table.

self:SendEvent {updateSharedData = {shootCount = self.ShootCount}}

newState causes force state transition on player side. You can change the state on each players like following:

self:SendEvent {newState = "Stat1"}


StateAllTrue
self:StateAllTrue (key)

Test if all elements are evaluated as true in one of column on PlayerStatus table.

Note that on Lua only nil and false are evaluated as false and all other data (including number 0 and empty string) are evaluated as true.

StateAllFalse
self:StateAllFalse (key)
StateAnyTrue
self:StateAnyTrue (key)
StateAnyFalse
self:StateAnyFalse (key)
ClearState
self:ClearState (key)

Clears all player's values indicated by key.

Read Only Data Members

PlayerStatus

(deprecated; use GetPlayerStatus() method.)

RoomData

Minigame room data.


Callback Functions

OnPlayerLeft
function ARMPMiniGameSampleMaster:OnPlayerLeft (num)

Called when a player left from the minigame. num is the index number of the player.

Example:

function ARMPMiniGameSampleMaster:OnPlayerLeft (num)
  System.Log ("ARMPMiniGameSampleMaster:OnPlayerLeft: " .. tostring (num))
end

Game Player

UpdateStatus
self:UpdateStatus (key, value)

Updates a value in the StatusData table on game master side.

key (string): key of the data.

value: value for the specified key. This can be any type of value except for function and userdata.

Broadcast
self:Broadcast (data)

Broadcasts data to all players. Playres can receive this data by OnBroadcast event handler.

data: may be any type of value except for function and userdata.

SendScoreAndGetRanking
self:SendScoreAndGetRanking (game_type, score, comment, func)

Sends score by the player to minigame matching server and get ranking.

game_type (string): type of your minigame.

score (number): score.

comment (string): comment. You can specify any string.

func (function): callback function to receive the ranking value (number) as an argument.

NOTE: Since func is called asynchronously, it is recommended to just set some variables in the callback function and treat these variables from other event handler (e.g. OnUpdate).

Example:

local function get_rank (rank)
  self.Rank = rank
end
self:SendScoreAndGetRanking ("AR:Example", score, "example game", get_rank)
 -- in a State definition
 OnUpdate =
   function (self, time)
     if self.Rank then
       ARDebugMessageF ("Your rank is %s", self.Rank)
       self.Rank = nil
     end
   end,


GetHistory
self:GetHistory (game_type, func)

Retrieves players game history data.

game_type (string): type of your minigame.

func (function): callback function to receive the history data (table) as an argument.

The history data is represented as a table (array) like following:

{
  {
    data="example game",
    type="AR:Example",
    score="188"
  },
  {
    data="example game",
    type="AR:Example",
    score="167"
  },
  {
    data="example game",
    type="AR:Example",
    score="230"
  },
  {
    data="example game",
    type="AR:Example",
    score="108"
  }
}

Each elements are tables which contains data, type and score values.

Example:

local function get_history_data (data)
  self.history_data = data
end
self:GetHistory ("AR:Example", get_history_data)
GetAvatarData
local data = self:GetAvatarData (player_number)

Gets specified player's avatar data. Returned value is a table which contains ClientID and Name field.


Example: used in Bowling.

Also see GetPlayerCount example below.


GetPlayerCount
self:GetPlayerCount ()

Returns number of players.

Example:

 for i = 1, self:GetPlayerCount () do
   local data = self:GetAvatarData (i)
   System.Log (string.format ("ARMPMiniGameSample.Stat2: %d: %s", data.ClientID, data.Name))
 end


GetLocalPlayerNumber
self:GetLocalPlayerNumber ()

Returns the local player's number.

Example:

 if self.SharedData.turn == self:GetLocalPlayerNumber () then
   ARDebugMessage ("SHOOT NOW!")
 else
   ARDebugMessageF ("WAITING FOR PLAYER %s SHOOT", self.SharedData.turn)
 end
ShowTextChat
self:ShowTextChat ()

Displays text chat.

SpawnAvatar
self:SpawnAvatar (player_number, position)

Spawns avatar entity and attach clothes and faces automatically.

Example:

     local pos = self:GetPos ()
     for i = 1, self:GetPlayerCount () do
       local p = SumVectors(pos, {x = 0, y = i, z = 0})
       local ent = self:SpawnAvatar (i, p)
       self.Entities[i] = ent
     end
DressUp (OBSOLETE)

(obsolete. Please use SpawnAvatar method instead)

self:DressUp (entity, player_number)

Attaches cloths and face on a avatar entity.

Example:

local pos = self:GetPos ()
for i = 1, self:GetPlayerCount () do
  local p = SumVectors(pos, {x = 0, y = i, z = 0})
  local ent = ARAvatar:SpawnAvatar ("player" .. i, nil, p)
  self:DressUp (ent, i)
end
Exit
self:Exit ()

Exits the minigame. Leaves from minigame room automatically and terminate all processes of minigame entity.

OnExit callback function is called before the player/master entity is destroyed.

Example:

ARMPMiniGameSample.GameOver = {
  OnBeginState =
    function (self)
      self:Exit ()
    end
}

Callback Functions

OnExit
function ARMPMiniGameSample:OnExit ()

Called when the minigame is terminated. You can release resources used in a game.

Example:

function ARMPMiniGameSample:OnExit ()
  for i, ent in pairs (self.Entities) do
    System.Log ("    Deleting entity #" .. tostring (i))
    ent:DeleteThis ()
  end
end
OnMasterLeft
function ARMPMiniGameSample:OnMasterLeft ()

Called when the game master left from the minigame. If this happen, you should terminate the minigame.

Example:

function ARMPMiniGameSample:OnMasterLeft ()
  ARDebugMessage ("ARMPMiniGameSample:OnMasterLeft")
  self:Exit ()  
end

Read Only Data Members

SharedData

Shared data table.

RoomData

Room data. Same as room master's one.

Example

Please see the example code at: /CryENGINE2/Game/Scripts/Entities/Minigames/AR/ARMPMinigameSample


Problems with this wiki page? Contact us either by: Support Email or Support Ticket System

Blue Mars Guidebook Privacy Policy
Blue Mars Guidebook Community Guidelines

Personal tools