Dbserver-to-mapserver

dbserver listens on port 6997 for its db service, and MapServer and RaidServer connect to it.

(For other services that dbserver presents, see Dbserver-protocols.)

Every NetLink for the db server has a unique lock_id, starting from 0. They are used to identify current connections to MapServer in order to send messages.

Commands with names starting with DBSERVER are sent by dbserver, and names starting with DBCLIENT are sent to dbserver.

DBCLIENT_INITIAL_CONNECT

optional packint(1) map_protocol

If map_protocol is not present (the body is empty), it is 0. If map_protocol is not equal to DBSERVER_PROTOCOL_VERSION (currently 20110503) then dbserver will respond with DBSERVER_CLIENT_CMD_FAILED and close the NetLink.

Otherwise, dbserver sends these commands back to the MapServer:

DBSERVER_TIMEOFFSET:

bits(32) seconds_since_2000
float32 time_zone_delta

These values are set based on the system clock. time_zone_delta is the difference between UTC and local time, in hours.

DBSERVER_OVERRIDDEN_AUTHBITS

bits(1024) overridden_auth_bits

The value of overridden_auth_bits is set based on OverrideAuthBit lines in servers.cfg.

If any DisabledZoneEvents entries are present in servers.cfg, dbserver sends a DBSERVER_DISABLED_ZONE_EVENTS command:

repeated string event

One entry for each DisabledZoneEvents line in servers.cfg

If user reactivation is active, dbserver sends a DBSERVER_NOTIFY_REACTIVATION message, with no body.

DBSERVER_UPDATE_LOG_LEVELS:

repeated LOG_LEVELS times:
  packint(1) log_level

These are the log levels, as managed by log.h, for all logging types in order from 0 to LOG_LEVELS. They are set in servers.cfg with SetLogLevel lines.

DBSERVER_ACCOUNTSERVER_CATALOG:

autobits catalog_timestamp
autobits auth_timeout
string mtx_environment
string play_span_domain
string play_span_url_home
string play_span_url_categoryview
string play_span_url_itemview
string play_span_url_showcart
string play_span_url_addtocart
string play_span_url_manageaccount
string play_span_url_supportpage
string play_span_url_supportpage_de
string play_span_url_supportpage_fr
string play_span_url_updatetovip
string coh_url_newfeatures
string coh_url_newfeaturesupdate
autobits play_span_store_flags

These appear to be values set in account_server.cfg. Most of them are URLs.

DBCLIENT_READY

This message is understood by dbserver, but does not appear to be sent by mapserver; it is suspected to be historical debris.

DBCLIENT_REGISTER

packint(1) map_id
packint(1) local_ip
packint(1) remote_ip
packint(1) udp_port
packint(1) tcp_port
packint(1) static_link
packint(1) cookie
string patch_version
optional string map_name

A MapServer sends this message when it starts up, immediately after DBCLIENT_INITIAL_CONNECT.

static_link is set based on the command line of the MapServer

map_id is a signed int, set on the command line of the MapServer. Negative values mean that a map_name field will be sent and edit mode will be used.

If map_id is non-negative, then dbserver selects the container for this mapserver based on map_id, and closes the link if the map_id is not known. Otherwise, dbserver selects the container based on map_name, and enables edit mode on this container. If static_link is set, then dbserver searches for a map with this name. If static_link is not set, or no map of this name is found, then a new map container is created and populated with the data in the map_name field.

udp_port and tcp_port are the ports on which the MapServer will listen for game clients, and are set on the command line.

cookie is set on the command line of the MapServer, and sent as-is. If the cookie is non-zero, then dbserver will validate that it matches the cookie matches the container referenced by map_id, and will close the link if it does not match. This is used to ensure the MapServer is the one this dbserver wanted to spawn, and not from a previous instance of dbserver.

local_ip and remote_ip are sent by the mapserver, based on the result of gethostbyname(NULL). They will use the first two results from this function. If one of those results is an rfc1918 address, or 127.0.0.1 (none of the other loopback addresses are recognised as "local"), then it will be local_ip; otherwise local_ip will be the first result from gethostbyname() and remote_ip will be the second.

The map container in the dbserver will have its link set to the link which sent this message, and will be marked starting and active. dbserver will respond to the MapServer with DBSERVER_CONTAINERS, sending the container for map_id followed by the containers for all static maps.

DBCLIENT_REGISTER_CONTAINER_SERVER

packint(1) list_id

The client attempts to claim ownership of the DbList identified by list_id. This is used by RaidServer to register itself with dbserver. Only one link may own a DbList at a time. If another link has claimed the DbList, then this one is marked as waiting for it. If the owner of the DbList is disconnected, then a link which is waiting for it will become the owner.

When a link becomes the owner of a DbList, then dbserver sends it a DBSERVER_CONTAINER_SERVER_ACK:

packint(1) list_id
packint(1) max_session_id

Owning a DbList affects the handling of DBCLIENT_CONTAINER_RELAY and DBCLIENT_REGISTER_CONTAINER_SERVER_NOTIFY messages.

DBCLIENT_REGISTER_CONTAINER_SERVER_NOTIFY

packint(1) notify_mask

All DbLists owned by this link have their notify mask set to notify_mask.

notify_mask is a bitmask, where each bit corresponds to a ContainerType value. For each bit set, when a notification for that DbList is available, a DBSERVER_CONTAINER_SERVER_NOTIFY will be sent:

packint(1) list_id
packint(1) container_id
packint(1) member_id
bits(1) is_added

Notifications are only sent for the addition of Ents (player characters loading onto a map), deletion of containers, and for adding and removing group members. When an Ent is added, an add notification is sent for all groups that Ent is currently a member of.

is_added is 1 if a thing is being added, and 0 if a thing is being removed.

container_id is the id of the container being updated - either the group where members are being added or removed, or the container being deleted.

member_id is 0 if the operation is the removal of a group (supergroup deletion, etc), or the member ID if the operation is adding or removing a member from a group.

DBCLIENT_READY_FOR_PLAYERS

packint(1) map_id

This message is sent by MapServer when it has finished settup in the map. It marks the MapCon as not starting. If the MapCon has been marked for shutdown in the dbserver, then the dbserver will respond with an empty DBSERVER_TEAM_LEFT_MISSION message.

DBCLIENT_CONTAINER_INFO

This message has no body. dbserver will respond with DBSERVER_CONTAINER_INFO:

packint(1) count
string dbserver_status
repeated count-1 times:
  string container_status

dbserver_status will be a string like "DbServer started on %s, Up %d hours, %d minutes"

container_status will be a string like "0040 Ent (1)", giving the number of allocated containers in the each DbList, and its name and ContainerType value.

DBCLIENT_REQ_CONTAINERS

packint(1) user_data
packint(1) list_id
packint(1) cmd
packint(1) count
repeated count times:
  packint(1) container_id

dbserver will respond to this message with DBSERVER_CONTAINERS, with some containers selected from DbList list_id. user_data is returned in the DBSERVER_CONTAINERS response.

If cmd is CONTAINER_CMD_LOAD_ALL, count is ignored and all containers in the list are selected. Otherwise, container_id values are sent in the message, and those containers are selected.

Depending on the command selected, three other operations might be performed on this list:

• With CONTAINER_CMD_LOCK_AND_LOAD, CONTAINER_CMD_LOAD_ALL, CONTAINER_CMD_TEMPLOAD, or CONTAINER_CMD_TEMPLOAD_OFFLINE the containers will be loaded if necessary. Otherwise, containers that are not loaded will return an error code of CONTAINER_ERR_DOESNT_EXIST for that container.
• With CONTAINER_CMD_LOCK or CONTAINER_CMD_LOCK_AND_LOAD the containers will be locked to this link. Any container which is already locked by another link will return an error code of CONTAINER_ERR_ALREADY_LOCKED for that container.
• With CONTAINER_CMD_TEMPLOAD or CONTAINER_CMD_TEMPLOAD_OFFLINE any containers that have to be loaded for this message will be unloaded after it is finished.
• With CONTAINER_CMD_TEMPLOAD_OFFLINE the special handling for offline players (???) is used.

DBCLIENT_SET_CONTAINERS

packint(1) list_id
packint(1) cmd
packint(1) callback_id
packint(1) count
repeated count times:
  packint(1) container_id
  packint(1) notdiff
  packint(1) debugdiff
  string str
  optional string debugdiff_str

debugdiff_str is only sent when debugdiff is not 0, otherwise it is skipped

dbserver stores the containers, and responds with DBSERVER_CONTAINER_ACK to most messages:

packint(1) list_id
packint(1) callback_id
packint(1) count
repeated count times:
  packint(1) ack_id

The ack_id values will be the container_id values that were updated.

One DBSERVER_CONTAINER_ACK response is sent after every update is applied, containing all acks so far (this appears to be a bug, and not used for anything). Acks are used by MapServer to return the container_id when creating containers, and otherwise ignored.

The exception to this are:

• when list_id is the AutoCommands list, in which case dbserver will instead respond by broadcasting a DBSERVER_CONTAINERS message to all active MapServers with the new container value
• when the container is a GroupCon type, and cmd is not CONTAINER_CMD_UNLOCK_NOMODIFY, in which case dbserver will instead respond by broadcasting a DBSERVER_CONTAINERS message to all interested links:
  • MapServers that are running members of a MapGroup
  • MapServers that have connected Ents for other groups
  • the MapServer for a supergroup base
  • the statserver for a statserver group
  • the link that sent the DBCLIENT_SET_CONTAINERS message)

In these cases, no DBSERVER_CONTAINER_ACK messages are sent.

Possible values for cmd are:

• CONTAINER_CMD_CREATE, in which case id must be -1 and the container will be created.
• CONTAINER_CMD_CREATE_MODIFY, in which case id may be -1 and the container will be created if no container with this id exists.
• CONTAINER_CMD_DELETE, which will mark the container for deletion. str is ignored.
• CONTAINER_CMD_UNLOCK, which will apply updates and then unlock the container if this link has it locked.
• CONTAINER_CMD_UNLOCK_NOMODIFY, which will unlocked the container if this link has it locked, and not attempt to update the container. str is ignored
• CONTAINER_CMD_TEMPLOAD, which will load the container before updating it, and unload it after updating it, regardless of whether it was already loaded.

All other values of cmd will apply the update to an existing container.

If an error occurs, dbserver will abandon processing of the rest of the message, and respond with DBSERVER_CLIENT_CMD_FAILED:

 packint(1) fail_code
 string str

This occurs in the following scenarios:

• id is -1 for commands other than CREATE and CREATE_MODIFY, or id being any value other than -1 for CREATE, will return CONTAINER_ERR_DOESNT_EXIST
• Parse errors for the container in str will return CONTAINER_ERR_CANT_COMPLETE_SERIOUS
• An attempt to create an Ent on an account without free character slots will return CONTAINER_ERR_CANT_COMPLETE
• An attempt to create an Ent where the character name cannot be parsed will return CONTAINER_ERR_CANT_COMPLETE
• For DbList other than maps, a container that exists must not be locked to a link other than this one, or it will return CONTAINER_ERR_ALREADY_LOCKED
• For DbList other than maps, and commands other than CREATE_MODIFY, the container must be locked or it will return CONTAINER_ERR_NOT_LOCKED
• If the container does not exist for whatever reason (after processing creation), it will return CONTAINER_ERR_DOESNT_EXIST

Applying container updates

str will be treated as a diff if notdiff is 0, or as a full copy of the container if notdiff is 1.

If the container does not have a template, then the string supplied always treated as a complete replacement, and the content of the container is simply set to this value, then special column processing is run.

If the container has a template, and notdiff is 1, then a diff will be computed from the current value of the template to the string supplied, and then processing will continue as if a diff had been sent.

If the container has a template, then the string will be parsed into a line list, and then merged into the current line list. Next, special column processing is run. The computed updates are then added to the queue of sql writes, and if the container has an update callback, it is called (this is probably a bug: it will be called twice).

Special columns processing begins by calling the update callback. It then runs through a list of commands, which identify fields in the line list by name. The values of these fields will be written into some address inside the DbContainer struct, as identified by the command. In the particular case of CMD_MEMBER, special tracking is done of memberships, which may result in sending notifications to servers that requested them with DBCLIENT_REGISTER_CONTAINER_SERVER_NOTIFY.

Special hackery

If the command is CREATE and the DbList is Ents (creating a player), then the player name will be uniquified (by appending or incrementing a number).

If the DbList is maps, and there is a map name in str, and a container with that name exists, then id is ignored and the container with that name is updated instead.

If the DbList is Ents and the container exists, and str contains a MapId field, then it must be equal to the map_id in the Ent or the server will assert (!!!).

If debugdiff is set, then the debugdiff_str field must be precisely equal to the observed diff to the container after the operation, or the server will assert (!!!).

If the command is CREATE and the DbList is Teamups, Supergroups, Taskforces, or Leagues, and the DbList is being stored in sql, then an sql barrier will be generated (all workers will synchronise).

If the DbList is maps, and the container is not being deleted, then dbserver will ask a launcher to start a MapServer if it does not have a link from a MapServer on this container.

DBCLIENT_CONTAINER_RELAY

packint(1) cmd
packint(1) list_id
packint(1) cid
packint(1) user_cmd
packint(1) user_data
... more data that dbserver does not parse

If list_id is not recognised, or no server has that DbList locked, then dbserver will respond with DBSERVER_CONTAINER_RECEIPT:

packint(1) cmd
packint(1) list_id
packint(1) cid
packint(1) user_cmd
packint(1) user_data
packint(1) error_code
string error_msg

where error_code will be CONTAINER_ERR_CANT_COMPLETE.

Otherwise, dbserver will forward the message to the server which has locked that DbList, as DBSERVER_CONTAINER_RELAY:

packint(1) cmd
packint(1) list_id
packint(1) cid
packint(1) user_cmd
packint(1) user_data
packint(1) lock_id
... everything else from the DBCLIENT_CONTAINER_RELAY is copied here

This is used for MapServer to send messages to RaidServer.

DBCLIENT_CONTAINER_RECEIPT

packint(1) lock_id
... more data that dbserver does not parse

dbserver finds the MapServer connection corresponding to lock_id and proxies the message to that MapServer as DBSERVER_CONTAINER_RECEIPT:

... all the data from the input message

This is used by RaidServer to acknowledge messages from MapServer.

DBCLIENT_CONTAINER_REFLECT

packint(1) list_id
packint(1) cmd
packint(1) target_count
repeated target_count times:
  packint(1) target_list
  packint(1) target_cid
  packint(1) target_dbid
  packint(1) del
packint(1) count
repeated count times:
  packint(1) id
optionally repeated count times:
  string data

data is present only when cmd is not CONTAINER_CMD_DELETE

If cmd is CONTAINER_CMD_CREATE_MODIFY, then dbserver will update each container id with the corresponding data, which is a full copy of the new container value. If cmd is CONTAINER_CMD_DELETE, then dbserver will delete each container id. No locking is checked for these updates.

dbserver now assembles a list of MapServers that these containers will be reflected to. The list is composed by going through the target block, and for each one:

• target_list is a list_id, target_cid is a container ID in that list
• If this target is a group container, and it is loaded, then the current MapServer for every loaded and connected member of that group is included
• If this target is an Ent, then its current MapServer is included
• If target_list is CONTAINER_MAPS and target_cid is -1, every MapServer is included
• If this target is a map, then its current MapServer is included
• If target_list is REFLECT_LOCKID then target_cid is a lock_id, not a container id, and the relevant MapServer is included

For each identified MapServer, dbserver sends it a DBSERVER_CONTAINER_REFLECT, with the same format as the input packet. The target list is changed to be the actual targets, discarding anything that could not be resolved to a MapServer.

DBCLIENT_REQ_CONTAINER_STATUS

packint(1) user_data
packint(1) list_id
packint(1) count
repeated count times:
  packint(1) id

If id is -1 then it means all active containers. If it is -2 then it means all containers. The concept of active means something different for different container types. Notably, the map for a connected MapServer, and an Ent that is connected to a MapServer, will both be active.

dbserver responds with DBSERVER_CONTAINER_STATUS:

packint(1) user_data
packint(1) list_id
packint(1) count
repeated count times:
  packint(1) exists
  string status

where status will be either a DbList-specific status string, or "%3d Active %d locked %d", populated with container id, active status, and locked status.

DBCLIENT_REQUEST_MAP_XFER

packint(1) map_id
string mapinfo
packint(1) find_best_map
packint(1) entity_id
bits(1) have_extra_data
optional autobits extra_crc
optional zipped extra_data

The extra_crc and extra_data fields are present only if have_extra_data is not 0. If this happens, dbserver will respond with an error. This appears to be a removed feature.

If mapinfo is not empty, then it identifies an instanced map. Otherwise, map_id identifies a specific map.

dbserver might override map_id to a different value in some scenarios (relating to Praetorian progression).

If find_best_map is 1, then dbserver will look for a clone of the map and select one based on the number of players currently on it.

If the map is instanced or static, a MapServer will be started for it.

The entity entity_id will be added to the list of entities waiting for this map, and when that MapServer is ready (possibly immediately), dbserver will send DBSERVER_MAP_XFER_READY to the MapServer which send the transfer request:

packint(1) entity_id
packint(1) new_map_id

DBCLIENT_MAP_XFER

packint(1) map_id
packint(1) count
repeated count times:
  packint(1) entity_id

Each entity in the list is processed separately.

dbserver might override map_id to a different value in some scenarios (relating to Praetorian progression).

If the map_id is the one where the entity is currently present, then dbserver responds with DBSERVER_MAP_XFER_FAIL:

packint(1) entity_id
string error_message

Otherwise, the entity container is unlocked, as the originated MapServer is giving up ownership of this entity, and the map transfer process begins, launching a new MapServer if necessary.

The entity container is updated with "MapId" set to the map id, and if the map is static, then also "StaticMapId" is set to the map id.

The entity is then locked to the MapServer for the new map id, and a DBSERVER_CONTAINERS is sent to that MapServer with the entity container.

Notifications are sent for the entity.

If the account for this entity has a loyalty status, then DBSERVER_ACCOUNTSERVER_LOYALTY is sent to the new MapServer:

autobits entity_id
bits(128) loyalty

DBCLIENT_CONTAINER_ACK

packint(1) list_id
packint(1) count
repeated count times:
  packint(1) id
  packint(1) cookie

If list_id is not CONTAINER_ENTS, the dbserver will treat it as an EntCon type anyway and probably crash (!!!).

MapServer only sends this message in response to DBSERVER_CONTAINERS for entities.

If cookie is 0, the entity will be deleted. If cookie is 1, the entity will be unloaded.

If this is part of a map transfer flow, then dbserver will send a DBSERVER_MAP_XFER_OK to the MapServer. If this is part of a login flow, then dbserver will send DBGAMESERVER_MAP_CONNECT to the game client (possibly via QueueServer). Either way, the message will contain:

packint(1) entity_id
packint(1) map_id
packint(1) ip
packint(1) ip
packint(1) udp_port
packint(1) tcp_port
packint(1) cookie

where ip is the same both times. ip, udp_port, and tcp_port are the connection information for the game client to connect to the new MapServer. cookie is copied from the input message.

After this, the entity is marked as active, and its logging in status is cleared.

DBCLIENT_TEST_MAP_XFER

packint(1) list_id // must be CONTAINER_ENTS
packint(1) map_id
packint(1) count // not used
packint(1) entity_id

dbserver sends DBSERVER_TEST_MAP_XFER to the MapServer where the entity is currently located, with a body identical to the message received.

DBCLIENT_SEND_DOORS

packint(1) map_id
packint(1) count
repeated count times:
  string door_info

dbserver finds the map map_id, and marks it as running.

If this map is not static, then dbserver continues as if count is 0 (no doors are sent), regardless of the data sent.

If the map has a base map, then that map is used instead for the remained of this message.

If door info was sent, each one is parsed in turn. dbserver scans existing doors to see if any are in approximately the same location. If none are found, then this door is added to the door containers. Any door containers that are not included in this list are deleted.

If any changes were made to door containers, then every eligible MapServer will be sent the door list; otherwise, only the MapServer which sent this request will be updated (if eligible). A MapServer is eligible for a door update if its map is static, or a supergroup base. A door list is sent in a DBSERVER_SEND_DOORS message:

packint(1) count
zipped data

where data is a zipped copy of all the door containers in text format.

DBCLIENT_SAVELISTS

This message has no body and receives no response. dbserver will write all the door containers to a flat file.

DBCLIENT_ADDDEL_MEMBERS

packint(1) list_id
packint(1) add
packint(1) id
packint(1) notdiff
packint(1) debug
string update
optional string not_used // present if debug is not 0
packint(1) count
repeated count times:
  packint(1) member_id
bits(1) autolock

If list_id is CONTAINER_SUPERGROUPS, then the container id will be loaded. Otherwise, the container id is selected only if it is loaded, and otherwise dbserver will respond with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_DOESNT_EXIST.

add mode

If add is not 0, then dbserver will attempt to add all members to the group.

If the group container is locked by a different link, or if autolock is set and the container is locked by this link, then dbserver will respond with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_ALREADY_LOCKED.

If autolock is set and update is not the empty string, dbserver will respond with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_NOT_LOCKED.

Otherwise, the change will be applied.

When an add operation is applied:

• If update is not the empty string, then it is applied to the container. If notdiff is set then it replaces the container, otherwise it is applied as a diff.
• All members are added to the container (which must be a group. bug: dbserver will break if it is not).
• If autolock is set then the group will be locked
• If the group is locked then dbserver will respond with DBSERVER_CONTAINERS, containing the new value of the group.
• If the group is not locked (which means this is adding members without updating the container), then dbserver will instead broadcast the container in the same way as DBCLIENT_SET_CONTAINERS does.

remove mode

If add is 0, then dbserver will attempt to remove all members from the group.

If autolock is set and the group is not locked, dbserver will respond with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_NOT_LOCKED.

If the group is locked by a different link, dbserver will respond with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_ALREADY_LOCKED.

Otherwise, the change will be applied.

When a remove operation is applied:

• If update is not the empty string, then it is applied to the container. If notdiff is set then it replaces the container, otherwise it is applied as a diff.
• All members are removed from the container (which must be a group. bug: dbserver will break if it is not).
• If autolock is set, then the group is unlocked
• If the group is locked then dbserver will respond with DBSERVER_CONTAINERS, containing the new value of the group.
• If the group is not locked (which happens if autolock is set), then dbserver will instead broadcast the container in the same way as DBCLIENT_SET_CONTAINERS does.

DBCLIENT_PLAYER_DISCONNECT

packint(1) entity_id
packint(1) logout
packint(2) logout_login

If entity_id is not loaded, does not exist, or is locked by another link, then dbserver does nothing and processing stops.

If logout_login is 2 and the queue server is in use, then the entity's account name is added to the auto-login list.

If the entity is in the queue, then it is unlocked and dbserver does nothing.

If logout is 0 or logout_login is 2 then the account will not be logged out.

Otherwise:

• The entity container is backed up.
• If logout is not 0 or logout_login is not 2 then account logout is sent:
  • dbserver sends ACCOUNT_CLIENT_LOGOUT_ACCOUNT to accountserver
  • dbserver sends AS_QUIT_GAME to authserver, with reason set to 4
• The player is unloaded:
  • dbserver sends DBSERVER_REMOVE_FROM_QUEUE to turnstileserver, with remove_from_group set to 1
  • If the entity is part of a Teamup, then they are removed from it.
  • If the entity is part of a League, then they are removed from it, and statserver is sent DBSERVER_SEND_STATSERVER_CMD, with command set to "statserver_league_quit %d 0 0" % entity_id
  • If the entity was waiting for transfer to a mapserver, then its game client is sent an error message, as DBGAMESERVER_MSG or DBSERVER_MAP_XFER_FAIL.
  • The entity is unloaded

DBCLIENT_SEND_MSG

packint(1) list_id
packint(1) msg_type
packint(1) sender_id
packint(1) count
string msg
repeated count times:
  packint(1) id

For each id in list_id, msg is broadcast to that container. If id is -1, then all containers in that DbList are broadcast to.

For each container being broadcast to:

If list_id is a group DbList, then all entities in the group are selected. If it is a Supergroup, and it has a base, then the mapserver for that base is also selected. If it is a statserver group, then statserver is also selected.

If list_id is a MapGroup, all mapservers for that group are selected.

DBSERVER_BROADCAST_MSG is sent to all selected links, with the same parameters as the original message. However, instead of the original list of ids, it will be either the member list of the group (if list_id is a group), or the entity (if list_id is CONTAINER_ENTS), or empty for all other DbLists.

DBCLIENT_REQ_GROUP_NAMES

packint(1) list_id
packint(1) count
repeated count times:
  packint(1) id

If any of the containers id in list_id are not loaded, then an SQL query will be run to get the Name field of every container. Otherwise, the response will be sent from loaded containers. In both cases the response should be the same.

dbserver responds with DBSERVER_SEND_GROUP_NAMES:

packint(1) list_id
packint(1) count
repeated count times:
  packint(1) id
  string name

where name is the Name field of each container.

DBCLIENT_REQ_ENT_NAMES

packint(1) list_id
packint(1) count
repeated count times:
  packint(1) entity_id

list_id should be CONTAINER_ENTS but is ignored.

dbserver responds with DBSERVER_SEND_ENT_NAMES, populating it with every entity in the request:

packint(1) list_id
packint(1) count
repeated count times:
  packint(1) entity_id
  string name
  packint(3) gender
  packint(3) name_gender
  packint(1) player_type
  autobits player_sub_type
  autobits player_type_by_location
  autobits praetorian_progress
  packint(1) auth_id

list_id in the response will be equal to the input, even though the response is always from CONTAINER_ENTS.

DBCLIENT_CONTAINER_FIND_BY_ELEMENT

packint(1) list_id
string element
string value
packint(1) online_only
packint(1) search_offline_ents

If list_id is CONTAINER_MAPS, then value is interpreted as an integer and the map with this ID is selected.

For all other values of list_id, element is a field name and value is an exact value to search for. A container with that value will be selected. The value is a string, unless the field is ContainerId, when it will be an integer.

If online_only is set and either:

• element is ContainerId
• element is Name and the DbList is entities or a group

then only loaded containers will be searched.

If element is Name, list_id is CONTAINER_ENTS, and a container has not yet been found, then special handling of offline players is performed (???).

dbserver responds with DBSERVER_CONTAINER_ID:

packint(1) list_id
packint(1) id
packint(1) map_id

where id will be -1 if no container was found, and map_id will be -1 unless the container is an active entity, in which case it will be the id of that entity's current map.

DBCLIENT_SHUTDOWN

string msg

When this message is received, the dbserver will shutdown.

The following steps will occur:

• All backups are flushed.
• All mapservers (other than the one used by the client from which this command was sent) are sent DBSERVER_SHUTDOWN and turnstileserver is sent DBSERVER_TS_CRASHEDMAP for each non-static map where mission_info starts with the letter 'E'.
• dbserver waits for 60 seconds, or until all non-edit-mode mapservers are inactive.
• The same procedure is run for the mapserver used by the client from which this command was sent.
• All pending SQL commands are flushed, and dbserver waits for them to finish.
• dbserver attempts to shut down the logging thread, waiting up to 8 minutes
• The dbserver process exits

The DBSERVER_SHUTDOWN message sent to mapservers will be:

packint(1) terminal
string msg

where terminal is 1 and msg is the string passed in the request.

DBCLIENT_WHO

string cmd

The rest of the request depends on the value of cmd. In all cases, the response is DBSERVER_WHO:

string msg

where the contents of the message is a string intended for display to a user.

serverwho

packint(1) map_id

If map_id is negative, dbserver reports on the number of zone (static), edit mode, and mission maps, and sums the rest of the stats for all of them. Otherwise, dbserver reports on the single map selected.

dbserver reports on the number of players playing and connecting, the number of entities, and the number of monsters.

who

string name

If the named player is online, dbserver reports on their account and auth, group memberships, and location.

supergroupwho

string name

dbserver reports on the supergroup allies and members.

teamupwho, raidwho, levelingpactwho, leaguewho

packint(1) id

dbserver finds the relevant group and reports its members

DBCLIENT_SERVER_STATS_UPDATE

packint(1) num_entities
packint(1) num_players
packint(1) num_monsters
packint(1) num_players_connecting
float32 ticks_sec
float32 long_tick
packint(1) num_hero_players
packint(1) num_villain_players
packint(1) num_relay_cmds
optional packint(9) average_ping
optional packint(9) min_ping
optional packint(9) max_ping

This is message is sent by mapserver to record its stats in ram. It is used for relaying to ServerMonitor and to respond to DBCLIENT_WHO.

DBCLIENT_RELAY_CMD

packint(1) map_id
string msg

If server_id is negative, all active MapServers are selected. Otherwise, the MapServer for this map is selected.

The selected servers are sent DBSERVER_RELAY_CMD:

string msg

DBCLIENT_RELAY_CMD_BYENT

packint(1) entity_id
packint(1) force
string msg

If force is not 0 and the entity is not online, they are loaded onto their last map.

dbserver responds with DBSERVER_RELAY_CMD_RESPONSE:

packint(1) success
optional packint(1) online

where success is 1 if the player is online or force is not 0, and online is sent only if success is 1, and will be 1 if the player is online.

DBSERVER_RELAY_CMD is sent to the MapServer where the player is loaded:

string msg

DBCLIENT_RELAY_CMD_TOGROUP

packint(1) id
packint(1) list_id
string msg

list_id must be a group, or dbserver will break (bug).

All members of the group identified by list_id and id will have DBSERVER_RELAY_CMD sent to their mapserver:

string msg

DBCLIENT_REQ_ONLINE_ENTS

packint(1) arena_map
packint(1) mission_map
packint(1) coed_faction_map
packint(1) coed_universe_map
autobits count
repeated count times:
  autobits entity_id
  packint(1) faction_same_map
  packint(1) universe_same_map

All loaded entities in the list are updated with the map settings given.

The data returned by dbserver is cached, with a 5 second TTL. It will be computed when this message is sent, if necessary.

dbserver responds with DBSERVER_ONLINE_ENTS:

bits(32) bit_length
bits(32) size
zipped stream

where these three fields describe a byte-aligned bitstream and its contents. The contents of that bitstream are:

repeated:
  packint(20) entity_id
  packint(8) map_id
  packint(8) static_map_id
  packint(4) team_member_count
  packint(1) entity_is_team_leader
  packint(10) hide_field
  packint(10) lfg_field
  packint(6) level
  string archetype
  string origin
  packint(2) player_type
  packint(2) player_type_by_location
  packint(2) player_sub_type
  packint(3) praetorian_progress
  packint(1) arena_map
  packint(1) mission_map
  packint(1) can_co_faction
  packint(1) faction_same_map
  packint(1) can_co_universe
  packint(1) universe_same_map
  bits(32) last_active
  bits(32) member_since
  bits(32) prestige
  packint(8) league_member_count
  packint(1) is_league_leader
packint(20) zero // will be 0

Each entry describes one entity; all online players are included.

DBCLIENT_REQ_ONLINE_ENT_COMMENTS

This request has no body.

dbserver caches the response data with a 5 second TTL.

dbserver will respond with DBSERVER_ONLINE_ENT_COMMENTS:

repeated:
  packint(20) entity_id
  string comment
packint(20) zero // will be 0

One entry will be sent for each logged-in player.

DBCLIENT_PLAYER_KICKED

packint(1) player_id
packint(1) ban

If player_id is not a loaded entity, nothing happens.

Otherwise, dbserver sends AS_KICK_ACCOUNT (when ban is 0) or AS_BAN_USER (when ban is not 0) to authserver:

U32 auth_id
U16 reason

where reason will be 0.

DBCLIENT_REQ_CUSTOM_DATA

bits(32) callback
packint(1) container_id
string limit
string restrict
string columns
packint(1) list_id
string table_name

dbserver runs an sql query on the named table, using the given query parameters, for the container identified by list_id and container_id.

If container_id is 0, dbserver will insert a write barrier before running the query.

It responds with DBSERVER_CUSTOM_DATA:

bits(32) callback
packint(1) container_id
packint(1) row_count
repeated row_count times:
  oneof:
    string attribute
    string str
    packint(1) number
    float32 float
    bits(32) time

The caller has to know the data types in the table in order to parse the packet.

DBCLIENT_EXECUTE_SQL

string statement

The SQL statement is executed on the database. No response is returned. No barriers are used, so ordering is unpredictable.

This is used in exactly one place, in the email system.

DBCLIENT_DISCONNECT_MAPSERVER

packint(1) map_id

If map_id is at least CRASHED_MAP_BASE_ID (90000) then it identifies a CrashedMaps container, which will be deleted.

If map_id is at least 0 and less than CRASHED_MAP_BASE_ID then it identifies a maps container and associated MapServer. If it has a link, that link will be disconnected. Otherwise, its container will be freed immediately. In either case, all entities on the map will be logged out. If it has been over 15 seconds since a message was received for this map, then a CrashedMaps container will be created and special handling for launcher crashes will be run.

If map_id is negative, this process will be run on all MapServers which have not responded in 30 seconds. If map_id is -2, MapServers which are starting will be included, otherwise they will be skipped.

DBCLIENT_PLAYER_RENAME

packint(1) callback
packint(1) entity_id
string name

If entity_id is not loaded, dbservers responds with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_DOESNT_EXIST.

name will be escaped (backslashing \ \n \r \t " ' % characters). If the resulting string is the same as the current name ignoring case, then the name change will be allowed, otherwise it will be checked for collisions with existing entities and will return DBSERVER_CLIENT_CMD_FAILED with error code CONTAINER_ERR_CANT_COMPLETE if there is one.

The entity container will be updated with the new name, and dbserver will respond with DBSERVER_CONTAINER_ACK:

packint(1) list_id
packint(1) callback
packint(1) count // will be 1
packint(1) entity_id

DBCLIENT_PLAYER_CHANGETYPE

packint(1) callback
packint(1) entity_id
packint(1) player_type

If entity entity_id is not loaded, dbserver responds with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_DOESNT_EXIST.

The player type is set to player_type, and dbserver responds with DBSERVER_CONTAINER_ACK.

DBCLIENT_PLAYER_CHANGESUBTYPE

packint(1) callback
packint(1) entity_id
packint(1) player_sub_type

If entity entity_id is not loaded, dbserver responds with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_DOESNT_EXIST.

The player subtype is set to player_sub_type, and dbserver responds with DBSERVER_CONTAINER_ACK.

DBCLIENT_PLAYER_CHANGEPRAETORIANPROGRESS

packint(1) callback
packint(1) entity_id
packint(1) praetorian_progress

If entity entity_id is not loaded, dbserver responds with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_DOESNT_EXIST.

The praetorian progress is set to praetorian_progress', and dbserver responds with DBSERVER_CONTAINER_ACK.

DBCLIENT_PLAYER_CHANGEINFLUENCETYPE

packint(1) callback
packint(1) entity_id
packint(1) influence_type

If entity entity_id is not loaded, dbserver responds with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_DOESNT_EXIST.

The influence type is set to influence_type', and dbserver responds with DBSERVER_CONTAINER_ACK.

DBCLIENT_DEPRECATED

This message is ignored.

DBCLIENT_RENAME_RESPONSE

string auth_name
string name

dbserver finds the game client identified by auth_name and sends it DBGAMESERVER_RENAME_RESPONSE:

string name

DBCLIENT_CHECK_NAME_RESPONSE

autobits auth_id
string result
autobits success
autobits temp_lock_name

dbserver finds the game client link identified by auth_id. If no such link exists, processing ends here.

If success is not 0 and temp_lock_name is not 0, dbserver will add a temporary lock on the name.

dbserver sends the game client DBGAMESERVER_CHECK_NAME_RESPONSE:

autobits success
autobits temp_lock_name

where temp_lock_name will be set to 0 if success is 0, and otherwise will be the same as the request.

DBCLIENT_DELETE_PLAYER

autobits entity_id

If a MapServer has entity entity_id locked, it will be sent DBSERVER_FORCE_LOGOUT:

packint(1) entity_id
packint(1) reason

where reason will be -3.

If no MapServer has the entity loaded, then authserver and accountserver will be notified of the logout with reason 6.

The entity container will be moved to offline storage with status kOfflineObjStatus_DELETED.

The entity will then be deleted, removing it from all groups and sending notifications.

DBCLIENT_MAP_SET_MARTY_STATUS

bits(1) marty_enabled

This message sends DBSERVER_RELAY_CMD to all MapServers, with:

cmdrelay
SetMARTYStatusRelay %i

populated with marty_enabled.

It also records the state of the flag in server_cfg, which does not do anything (bug: because MapServer flags are only computed on startup).

DBCLIENT_GRANT_CHARSLOT

autobits auth_id
autobits delta

The ShardAccount auth_id will be loaded, and delta will be added to its SlotCount field.

DBCLIENT_PLAYER_UNLOCK

autobits callback_id
autobits entity_id

If entity_id is not loaded, dbservers responds with DBSERVER_CLIENT_CMD_FAILED, error code CONTAINER_ERR_DOESNT_EXIST.

The entity's container is updated to set IsSlotLocked to 0.

The ShardAccount of the entity is updated to set ShowPremiumSlotLockNag to 0.

dbserver responds with DBSERVER_CONTAINER_ACK.

DBCLIENT_DEBUG_SET_VIP

autobits auth_id
autobits vip

Nothing happens unless fake auth is enabled.

If fake auth is used, the ShardAccount vip status is set to vip.

DBSERVER_TIMEOFFSET

bits(32) time
float32 timezone_delta

time is expressed as seconds since 2000.

dbserver sends this message in response to DBCLIENT_INITIAL_CONNECT. MapServer uses it to approximately synchronise its clock with dbserver, in case MapServer instances are running on machines with incorrectly set clocks.

DBSERVER_CONNECT_DENIED

Not used.

DBSERVER_CONTAINERS

packint(1) user_data
packint(1) list_id
packint(1) count
repeated count times:
  packint(1) id
  packint(1) has_error
  packint(1) is_map_xfer
  packint(1) is_static_map
  packint(1) locked
  packint(1) is_deleting
  packint(1) demand_loaded
  packint(1) member_count
  repeated member_count times:
    packint(1) member_id
  string text

If has_error is 1, then the block for this container is replaced by:

  packint(1) map_id
  packint(1) has_error
  packint(1) error_code

The error_code will be CONTAINER_ERR_DOESNT_EXIST if the container was not found or not loaded, and CONTAINER_ERR_ALREADY_LOCKED if this was an attempt to lock the container and another link already has this container locked. In all cases, errors are on a per-container basis, and the rest of the request will be processed.

This message is used to send containers to the MapServer. It will be sent when:

• responding to DBCLIENT_REGISTER, to send map containers
• responding to DBCLIENT_REQ_CONTAINERS
• broadcasting the results of DBCLIENT_SET_CONTAINERS to interested MapServers
• loading an entity onto a MapServer, as part of login (when handling DBGAMECLIENT_CHOOSE_PLAYER or DBGAMECLIENT_CHOOSE_VISITING_PLAYER) or map transfer (when handling DBCLIENT_MAP_XFER from another MapServer)
• when handling DBCLIENT_ADDDEL_MEMBERS, either responding or broadcasting the result

The contents of the container is represented in the text string.

user_data is only set in response to DBCLIENT_REQ_CONTAINERS, and is 0 in other scenarios. It returns the value sent in the request. (bug!!! MapServer packs a pointer into this field, which may break on 64-bit systems)

locked will be 1 if the container has now been locked to this link, and 0 if the locking state is unchanged.

If the container is a group, then a member_id list will be sent. Otherwise, member_count will be 0.

is_map_xfer will be 0 unless the container is an Ent.

is_static_map will be 0 unless the container is a Map.

MapServer handles this message differently depending on whether user_data is set, or on the value of list_id. If user_data is not 0, then MapServer interprets it as a function pointer and calls it. This will be a callback function that was originally passed to dbAsyncContainerRequest or dbSyncContainerRequestCustom.

Otherwise, if the container is an Entity, then MapServer will load all of the containers, generate login cookies for them, and respond with DBCLIENT_CONTAINER_ACK to send the cookies back to dbserver.

Otherwise, if the container is a map, then if this is the first map received since sending DBCLIENT_REGISTER then this is stored as the map for this MapServer, and MissionInfo is parsed. This sets up the MapServer as an arena, sgbase, raid, endgame raid, or mission. Regardless of whether or not this is the first map, the container is read and the map name is added to the name/id lookup table.

For all other scenarios, including the case where dbSyncContainerRequest was called with the no_process flag, the container is simply read into cache. If the container is an Entity, MapGroup, Group, or AutoCommand then MapServer has extra processing to do.

For an Entity:

• If this Entity is already loaded, and has a client link, then this is a reconnecting client and the old link is disconnected.
• The Entity is fully unpacked into memory. See Entity_(container)#unpackEnt for a detailed discussion.
• If the Entity last logged in over 15 minutes ago, then the character is reset (clearing hitpoints, endurance, powers, buffs, toggles, etc)
• Synchronous container requests are sent for the taskforce, supergroup, teamup, levelingpact, and league which the Entity is a member of, waiting for a response to each before continuing (which means those containers are fully processed)
• MapListRefresh:%d is broadcast to all members of the teamup and league, with the ID of the current map
• Alignment is updated based on the map that the Entity has loaded into, if necessary
• A custom SQL query is sent to dbserver for supergroup members
• If the Entity is in a supergroup, DBCLIENT_CONTAINER_RELAY is sent for CONTAINER_BASERAIDS (should notify RaidServer that the player has logged in)
• The Entity is placed on the map, according to dbflags indicating which door they enter from
• If this is a map transfer, then LinkEnt and Status are sent to dbserver as LOG_SHARDCHAT messages
• If this is a fresh login, then teamup and league memberships are cleared, taskforce membership is restored, and a task is selected
• If the character is dead, they are positioned appropriately
• MapServer attempts to repair corrupted Entities and SuperGroups
• A login cookie is generated
• The teamup is updated, and sent to dbserver

For a MapGroup:

• If this MapGroup has an active event, and it is not currently running, then the relevant script is started

For a Group:

• If this is the architect taskforce for this MapServer, it is loaded and set up
• For each member, the relevant parts of the group are unpacked into the Entity
• If the container is not locked by this message, then deletes and leaders are checked and updates sent to the game clients involved
• If the team is coed (mixed factions) and this map does not allow that, kick from the team as needed.