func AfterBroadcastRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
AfterBroadcastRoomCmd registers a callback function to be executed after broadcast room command: Must be called before ExposeCommands
func AfterCreateRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
AfterCreateRoomCmd registers a callback function to be executed after create room command: Must be called before ExposeCommands
func AfterGetRoomPropCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
AfterGetRoomPropCmd registers a callback function to be executed after get room properties: Must be called before ExposeCommands
func AfterJoinRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
AfterJoinRoomCmd registers a callback function to be executed after join room command: Must be called before ExposeCommands
func AfterLeaveRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
AfterLeaveRoomCmd registers a callback function to be executed after leave room command: Must be called before ExposeCommands
func AfterMessageRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
AfterMessageRoomCmd registers a callback function to be executed after message room command: Must be called before ExposeCommands
func AfterUpdateRoomPropCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
AfterUpdateRoomPropCmd registers a callback function to be executed after update room properties: Must be called before ExposeCommands
func Announce(roomID string, memberIDs []string, ver uint8, cmd uint16, message []byte, reliable bool)
Announce Sends a message to selected members to the room without having a "sender" - This function must NOT be called by user
roomID string - Target room ID. memberIDs []string - An array of member user IDs to send message to. senderUser *user.USer - User to send broadcast. ver uint8 - Command version to be used as broadcast message. cmd uint16 - Command ID to be used as broadcast message. message []byte - Message byte array. reliable bool - If true, UDP will be RUDP.
func BeforeBroadcastRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
BeforeBroadcastRoomCmd registers a callback function to be executed before broadcast room command: Must be called before ExposeCommands
func BeforeCreateRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
BeforeCreateRoomCmd registers a callback function to be executed before create room command: Must be called before ExposeCommands
func BeforeGetRoomPropCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
BeforeGetRoomPropCmd registers a callback function to be executed before get room properties: Must be called before ExposeCommands
func BeforeJoinRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
BeforeJoinRoomCmd registers a callback function to be executed before join room command: Must be called before ExposeCommands
func BeforeLeaveRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
BeforeLeaveRoomCmd registers a callback function to be executed before leave room command: Must be called before ExposeCommands
func BeforeMessageRoomCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
BeforeMessageRoomCmd registers a callback function to be executed before message room command: Must be called before ExposeCommands
func BeforeUpdateRoomPropCmd(callback func(uint8, uint16, []byte, *user.User, func(error)))
BeforeUpdateRoomPropCmd registers a callback function to be executed before update room properties: Must be called before ExposeCommands
func Broadcast(roomID string, senderUser *user.User, ver uint8, cmd uint16, message []byte, reliable bool)
Broadcast Sends a broadcast message to the other members in the room
roomID string - Target room ID. senderUser *user.USer - User to send broadcast. ver uint8 - Command version to be used as broadcast message. cmd uint16 - Command ID to be used as broadcast message. message []byte - Message byte array. reliable bool - If true, UDP will be RUDP.
func CancelReservation(roomID string, userData *user.User, memberIDs []string, mustBeOwner bool) error
CancelReservation removes reservation per members
room ID string - Target room ID to cancel a reservation. userData *user.User - Owner user to cancel the reservation. memberIDs []string - An array of user IDs to cancel the reservation for. mustBeOwner bool - If true userData must be the room owner
func CancelReservationRemote(roomID string, userData *user.User, memberIDs []string, mustBeOwner bool, cb func(error))
CancelReservationRemote removes reservation per members
room ID string - Target room ID to cancel a reservation. userData *user.User - Owner user to cancel the reservation. memberIDs []string - An array of user IDs to cancel the reservation for. mustBeOwner bool - If true userData must be the room owner cb - Callback function
func ChangeTTL(roomID string, ttl int64) bool
ChangeTTL changes TTL of the targetted room
room ID string - Target room ID to change its TTL. ttl int64 - New TTL of the room.
func DeleteRoom(roomID string, userData *user.User, ver uint8, cmd uint16, message []byte)
DeleteRoom deletes the target room regardless of the room being not empty and sends notification message to its members.
roomID string - Target room ID to delete. userData *user.User - User that performs the deletion of the room. ver uint8 - Command version to send the notification as. cmd uint16 - Command ID to send the notification as. message []byte - Message byte array to be sent to the members.
func Exists(roomID string) bool
Exists return true if the given roomID's room still exists
roomID string - Target room ID to check if the room exists or not.
func ExposeCommands()
ExposeCommands Exposes TCP or UDP/RUDP commands to execute room functions from the client
func GetAllRoomIDsOnNode() []string
GetAllRoomIDsOnNode returns all valid room IDs on the current node
func GetCreatedTime(roomID string) int64
GetCreatedTime returns the created time (in seconds) of the room
func GetMapping(roomID string) *mapping.Mapping
GetMapping returns a struct instance of mapping. room.UseMapping() must be called to use this
roomID string - Target room ID to get its mapping object.
func GetMemberByID(roomID string, id string) *user.User
GetMemberByID returns member user by room ID and user ID
roomID string - Target room ID to get the member *user.User from. id string - Target user ID to get *user.User of.
func GetMemberIDs(roomID string) []string
GetMemberIDs returns the list of member IDs (not SIDs)
roomID string - Target room ID to get the list of member user IDs.
func GetMemberIDsAndOwner(roomID string) ([]string, string, string)
GetMemberIDsAndOwner returns an array of all member IDs and owner ID and ownerSID
roomID string - Target room ID to get the list of member user IDs and its owner user ID from. Returns member user IDs as an array, owner user ID, and owner user SID.
func GetMemberSIDs(roomID string) []string
GetMemberSIDs returns the list of member SIDs
roomID string - Target room ID to get a list of member SIDs.
func GetMemberSIDsAndOwner(roomID string) ([]string, string, string)
GetMemberSIDsAndOwner returns an array of all member IDs and owner ID and owner SID
roomID string - Target room ID to get the list of member SIDs, owner user ID, and owner SID.
Returns an array of member user SIDs, owner user ID, and owner SID.
func GetMemberUsers(roomID string) []*user.User
GetMemberUsers returns the list of member user struct instances
roomID string - Target room ID to get the list of member userData.
func GetMemberUsersAndOwnerUser(roomID string) ([]*user.User, *user.User)
GetMemberUsersAndOwnerUser returns an array of all member IDs and owner ID
roomID string - Target room ID to get member *user.User and owner *user.User.
Returns member *user.User as an array and owner *user.User.
func GetNumberOfRoomMembers(roomID string, callback func(error, int, int))
GetNumberOfRoomMembers retrieves number of room members. This can be executed by anyone and they do not have to be part of the room.
roomID string - Target room ID to get the number of members from. callback func(error, int, int) - Callback to be invoked when the number of current members and max members retrieved.
IMPORTANT: This function works for all users including the users that are not members of the target room.
func GetProperties(roomID string) map[string]interface{}
GetProperties returns properties of a room
[IMPORTANT] Works with local rooms only
[IMPORTANT] Room properties do NOT support structs.
[IMPORTANT] when you handle properties, please use mesh.GetInt, mesh.GetInt8 etc as the value of properties maybe nil or float64
------------------
Operation example:
val := mesh.GetInt(properties, "counter")
properties["counter"] = val + 1 // increment by 1
-----------------------------------
Use datacapsule.Capsule as property
capsule := datacapsule.NewCapsule()
capsule.Import(properties["memberNum"]) // getting property as a capsule (assumes properties["memberNum"] as map[string]interface)
memberNum := capsule.GetAsInt8("memberNum")
roomID string - Target room ID of the properties.
func GetProperty(roomID string, name string) interface{}
GetProperty returns a property of the given room and property name. Returns nil if not found.
[IMPORTANT] Works with local rooms only
[IMPORTANT] Room properties do NOT support structs.
[IMPORTANT] when you handle properties, please use mesh.GetInt, mesh.GetInt8 etc as the value of properties maybe nil or float64
------------------
Operation example:
val := mesh.GetInt(properties, "counter")
properties["counter"] = val + 1 // increment by 1
-----------------------------------
Use datacapsule.Capsule as property
capsule := datacapsule.NewCapsule()
capsule.Import(properties["memberNum"]) // getting property as a capsule (assumes properties["memberNum"] as map[string]interface)
memberNum := capsule.GetAsInt8("memberNum")
roomID string - Target room ID of the properties.
name string - Property name to retrieve.
func GetRemoteProperties(roomID string, cb func(error, map[string]interface{}))
GetRemoteProperties returns properties of a room
[IMPORTANT] Works with local and remote rooms
[IMPORTANT] Room properties do NOT support structs.
[IMPORTANT] when you handle properties, please use mesh.GetInt, mesh.GetInt8 etc as the value of properties maybe nil or float64
------------------
Operation example:
val := mesh.GetInt(properties, "counter")
properties["counter"] = val + 1 // increment by 1
-----------------------------------
Use datacapsule.Capsule as property
capsule := datacapsule.NewCapsule()
capsule.Import(properties["memberNum"]) // getting property as a capsule (assumes properties["memberNum"] as map[string]interface)
memberNum := capsule.GetAsInt8("memberNum")
roomID string - Target room ID of the properties.
func GetRemoteProperty(roomID string, name string, cb func(error, interface{}))
GetRemoteProperty returns a property of the given room and property name. Returns nil if not found.
[IMPORTANT] Works with local and remote rooms
[IMPORTANT] Room properties do NOT support structs.
[IMPORTANT] when you handle properties, please use mesh.GetInt, mesh.GetInt8 etc as the value of properties maybe nil or float64
------------------
Operation example:
val := mesh.GetInt(properties, "counter")
properties["counter"] = val + 1 // increment by 1
-----------------------------------
Use datacapsule.Capsule as property
capsule := datacapsule.NewCapsule()
capsule.Import(properties["memberNum"]) // getting property as a capsule (assumes properties["memberNum"] as map[string]interface)
memberNum := capsule.GetAsInt8("memberNum")
roomID string - Target room ID of the properties.
name string - Property name to retrieve.
func GetRoomID(userData *user.User) string
GetRoomID returns roomID that the user has joined
userData *user.User - Target user to get the room ID that the user is currently member of.
func GetRoomNodeAddressList(roomID string) ([]string, error)
GetRoomNodeAddressList returns a list of internal node addresses that the room is stored
roomID string - Target room ID to extract the server internal node addresses from.
Returns a list of server internal node addresses of the room and error if it fails.
func GetRoomOwnerID(roomID string) string
GetRoomOwnerID returns the user ID of the owner of the room
roomID string - Target room ID to get the owner from.
func IncrProperty(roomID string, propName string, delta int64) bool
IncrProperty increments int64 property by given delta.
The property must be created before you execute this function.
If the property does not exist, it creates the property.
roomID string - Target room ID. propName string - Target property name. delta int64 - Delta value to increment by.
func IsUserInRoom(roomID string, userData *user.User) bool
IsUserInRoom returns true if the user is in the room
room ID string - Target room ID to check. userData *user.User - Target user to see if the user is in the room.
func Join(
roomID string,
userData *user.User,
ver uint8, cmd uint16,
message []byte,
callback func(error, []string, string, int64),
)
Join Joins a room and notify the other members of the room on joining the room. If message is empty, Broadcast will not be sent.
[IMPORTANT] The room to join may not be on the same server process and if that is the case, the client will move to where the room is.
Join(roomID, userData, ver, cmd, message, callback func(error, memberIDs, ownerID, createdTime)) room ID string - Target room ID to join. userData *user.User - User to join the room. ver uint8 - Command version to be used for succuessful join message sent to other room members. cmd uint16 - Command ID to be used for successful join message sent to other room members. message []byte - Message byte array to be sent as successful message to other room members. If message is either nil or empty, the message will not be sent. callback func(error, memberUserIDs []string, roomCreatedTime int64) Callback to be invoked when join operation completes (both success and failure).
func Leave(roomID string, userData *user.User, ver uint8, cmd uint16, message []byte) error
Leave Leaves from a room and notify the other members on leaving. If message is empty Broadcast will not be sent.
roomID string - Target room ID to leave from. userData *user.User - User that will be leaving the room. ver uint8 - Command version to be used for message sent when leave is successful. cmd uint16 - Command ID to be used for message sent when leave is successful. message []byte - Message byte array to be sent as successful message to other room mebers. If message is either nil or empty, the message will not be sent.
func Message(roomID string, memberIDs []string, senderUser *user.User, ver uint8, cmd uint16, message []byte, reliable bool)
Message Sends a message to selected members of the room
roomID string - Target room ID. memberIDs []string - An array of member user IDs to send message to. senderUser *user.USer - User to send broadcast. ver uint8 - Command version to be used as broadcast message. cmd uint16 - Command ID to be used as broadcast message. message []byte - Message byte array. reliable bool - If true, UDP will be RUDP.
func MigrateRoom(userData *user.User, room *Room, callback func(error, string, string))
MigrateRoom migrates a room to another node and moves its members to the new room This is inteded to used when the current node is about to shutdown, but you need to keep the current room. callback(error newRoomID string, oldRoomID string)
userData *user.User - Owner user to perform the migration. room *Room - Room that is to be migrated. callback func(error, newRoomID string, oldRoomID string) - Invoked when migration operation is completed.
IMPORTANT: Migration will change the room ID.
func NewRoom(userData *user.User, maxMembers int, allowEmpty bool, join bool, ttl int64, interval int64) (string, error)
NewRoom Creates a new room
userData - User data struct maxMembers - Maximum number of members allowed to join the room allowEmpty - If true, the room will not be deleted until TTL expires even if all members leave join - If true, the creator user will join the room automatically ttl - TTL of the room when it is empty in seconds. The value must be greater than 0. Minimam is 10 seconds interval - Broadcast interval in milliseconds. interval below 100ms will be forced to 0. If it's 0, no packet merge
func Reserve(roomID string, userData *user.User, memberIDs []string, mustBeOwner bool) error
Reserve fixes the member of users to join and rejects everyone else.
roomID string - Target room ID to make a reservation. userData *user.User - Owner user of the room to make a reservation. memberIDs []string - An array of user IDs to make a reservation for. mustBeOwner bool - If true, userData must be the owner of the room.
func SetJoinCondition(cond func(string, *user.User) error)
SetJoinCondition registers a condition function to control room join. Returning an error will cause room join to fail
Join condition is NOT protected by mutext lock.
SetJoinCondition(condition func(roomID string, userData *user.User)) cond func(roomID string, userData *user.User) error - Custom function to be invoked before room join to evaluate join conditions.
func SetOnAnnounce(roomID string, cb func(string, uint8, uint16, []byte)) bool
SetOnAnnounce registeres a listener callback on Announce of room It captures Broadcast and Message as well
roomID string - Target room ID. cb func(roomID, ver uint8, cmd uint16, message []byte) - Callback to be invoked on every Broadcast and Message.
NOTE: ver and cmd passed to the callback are the ver and cmd used to send Broadcast or Message.
Usage Example: Useful when capturing and sending the message data to external database or service.
func SetOnCustomUserDiscardByID(roomID string, callback func(string, *user.User) (uint8, uint16, []byte)) bool
SetOnCustomUserDiscardByID registers a callback to be executed when a room member disconnects unexpected. The purpose of this callback is to use custom command ver, cmd, and message data to be sent to other members.
func SetOnDiscardCustomMessage(custom func(string, string, string) []byte) bool
SetOnDiscardCustomMessage sets a custom function to create a custom message on user discard to be sent to members The callback receives roomID string, user ID string, user SID string
custom func(roomID string, userID string, userSID string) []byte - Custom function to create a custom message byte array to be sent to other members. when the member client disconnects and leave.
func SetOnJoinByID(roomID string, callback func(string, *user.User) bool) bool
SetOnJoinByID registers a callback to be executed just before the join operation to evaluate, if the user should join or not. Returning value false will cause the join operation to fail.
func SetOnJoinCompleteByID(roomID string, callback func(string, *user.User)) bool
SetOnJoinCompleteByID registers a callback on join operation complete
func SetOnMigrated(callback func(string, string))
SetOnMigrated registers a callback on migrated - The callbacks will be invoked on the server node where the room is migrated to
callback func(newRoomID string, oldRoomID string) - Assign a callback to be invoked when migration is succssful.
func SetOnRoomChange(cb func(string, []string, map[string]interface{})) bool
SetOnRoomChange registers a callback function on room change such as create, join, leave, property updates
cb func(roomID string, memberUserIDs []string, roomProperties map[string]interface{})
func SetOnRoomDiscard(cb func(string)) bool
SetOnRoomDiscard registers a callback function on room deletions
cb func(roomID string) - Function to be invoked on room's deletion.
func SetOnRoomDiscardByID(roomID string, callback func(string)) bool
SetOnRoomDiscardByID registers a callback on room deletion by room ID
func SetOnRoomOwnerChange(cb func(interface{}))
SetOnRoomOwnerChange sets a callback for room owner change The paramter (interface{}) passed to the callback:
cb func(roomData interface{}) - Callback to be invoked when the room owner changes.
params["roomID"] = roomID string
params["ownerID"] = ownerID string
func SetOnRoomPropertyUpdate(cb func(interface{}))
SetOnRoomPropertyUpdate sets a callback for room property updates. The paramter (interface{}) passed to the callback:
cb func(roomData interface{}) - Callback to be invoked when room property changes.
params["roomID"] = roomID string
// Properties that have been changed
params["properties"] = properties interface{}.(map[string]interface{})
func SetOnTick(roomID string, callback func(string)) bool
SetOnTick registers a callback on every 5 seconds tick on a room
roomID string - Target room ID to set a tick callback. callback func(roomID string) - Callback to be invoked at every tick.
Useage Example: Use this to call matching.Add so that you may keep the room available for matchmaking as long as you with.
func SetOnTickStop(roomID string, callback func(string)) bool
SetOnTickStop assigns a callback to be invoked when room tick stops
func SetRollbackOnJoinFailureByID(roomID string, callback func(string, *user.User)) bool
SetRollbackOnJoinFailureByID registers a callback to perform rollback operations on join failure
func SetupAsTCPServer()
SetupAsTCPServer Sets up room package
func SetupAsUDPServer()
SetupAsUDPServer Sets up room package
func SetupAsWSServer()
SetupAsWSServer Sets up room package
func SetupBackup(backupNum int)
SetupBackup Enables room data backup to different nodes - maximum backup nodes you can set is 2
backupNum int - Number of backup servers.
func StopTick(roomID string)
StopTick stops room's tick event loop
func SyncCreateTime(roomID string, ver uint8, cmd uint16, memberIDs []string)
SyncCreateTime sends room's created time (in seconds) to the selected (or all) members of the room
roomID string - Target room ID. ver uint8 - Command version to be used for the message. cmd uint16 - Command ID to be used for the message. memberIDs []string - An array of member user IDs to sync the room creation time.
func ThrottledMessage(roomID string, memberIDs []string, senderUser *user.User, ver uint8, cmd uint16, throttleTime int64, message []byte, reliable bool)
ThrottledMessage sends a server push packet to the members given if the packet sent previously has past throttleTime previously set. If not, the packet will be "Dropped". throttleTime is in milliseconds.
func UpdateProperties(roomID string, operation func(properties map[string]interface{}) bool) map[string]interface{}
UpdateProperties updates or creates properties of a room and returns the updated or created properties.
[IMPORTANT] Works with local rooms only
[IMPORTANT] Room properties do NOT support structs.
[IMPORTANT] When you handle properties, please use mesh.GetInt, mesh.GetInt8 etc as the value of properties maybe nil or float64.
[IMPORTANT] operation function is protected by mutex lock, using another mutext lock within the function may cause a deadlock.
Operation example:
var updateErr error
_ := room.UpdateProperties(roomID, func(properties map[string]interface{}) {
capsule := datacapsule.NewCapsule()
err := capsule.Import(properties["roomPropertyCapsule"].(map[string]interface{}))
if err != nil {
// this is how to propergate an error
updateErr = err
return
}
counter := capsule.GetAsInt("counter")
counter++
capsule.SetAsInt("counter", counter)
properties["roomPropertyCapsule"] = capsule.Export()
})
if updateErr != nil {
// handle update error here
}
Use datacapsule.Capsule as property:
capsule := datacapsule.NewCapsule()
capsule.SetAsInt8("memberNum", memberNum)
properties["memberNum"] = capsule.Export() // setting capsule as a property
roomID string - Target room ID of the properties.
operation func(properties map[string]interface{}) bool - Callback function to perform update operations.
Must return true, when property (properties) is updated and false when there is no update.
func UseMapping(roomID string, fieldSize int64)
UseMapping enables mapping (in-room field module)
roomID string - Target room ID. fieldSize int64 - Size of the map to be created within the room.
Room Room data structure
type Room struct {
ID string
MaxMembers int
AllowEmpty bool
// an array of member SIDs
Members []string
// ID as key and SID as value
MemberIDs map[string]string
Properties map[string]interface{}
// contains filtered or unexported fields
}
func GetRoomByID(roomID string) *Room
GetRoomByID returns a room
roomID string - Target room ID to get the room object.