Documentation
At the bottom of this post you will be able to find all dedicated server documents attached. The latest version of these documents is also always available in the root folder of the dedicated server package downloaded from Steam.
---
I am really glad that the community already maintains a basic Dedicated Server HowTo. It is lacking information about the server's API, so I've decided to write some stuff down about it.
First, why does/will the API even exist...
DS without the API
Without the API the functionality of the dedicated server is quite limited. The usage flow is nearly the same as when running a peer to peer multiplayer session, and so are the features. The major usage difference for users is only the session creation, which now requires a special command-line to create a session on a dedicated server instead of a peer to peer session (hopefully maybe one day there will be GUI for that!).
Joining is then the same, and so is the overall flow of the gameplay on a DS. The "host" is still the creating player until the player disconnects, then it migrates to another player. And the host still controls the gameplay settings.
So the DS in this form does not provide much more than potentially improved networking. Instead of everyone communicating with everyone else during gameplay, which can be quite tricky and unstable as the session size grows too much, the simulation network traffic is routed through the DS. That should be much more friendly to uplink bandwidth of all players, and evade all kinds of NAT and router problems associated with peer to peer networking, leading to overall more reliable online experience.
Why the API
But player expect more from the dedicated server. And that's mostly being able to monitor and control the game from the server, which could mean anything from just deciding who can join the server (which we already support to some extent by password-protection, blacklist and whitelist options), to server rotating tracks, to server running automatic leagues with overall scores as well as live race details displayed on a website.
Instead of implementing all kinds of those features directly into the server, the aim is to make the server as open as possible, or "moddable". This will allow the community to then implement any additional functionality based on their needs, instead of being restricted to what we might design and code in our unfortunately rather limited time.
Two API types
The server implements two kinds of API:
1. HTTP API, documented in this post
2. Lua API / scripting, documented in the attached pdf.
What does the API do
The API is intended to work in two ways:
1. It provides information about the server's and gameplay status / other data. The game sends the data to the server, and the API can be used to read the data. This can be split into few sub-categories.
1a. Static information. Such as self-generated help about the API, or various lists (all known vehicles, tracks, session attributes and so on)
1b. Server/session/gameplay status. A snapshot of current state of the server, multiplayer game running on it (if any), players connected to the session, and cars racing.
1c. Events. The server also receives events and provides a history of the events via the API. This range from "game started on the server" to "player joined/left the game" to "John collided with Joe, impact strength 500".
2. It provides a way for third-party apps to control the server, and via the server control the game. Controlling the game is an optional "mode" of the server, in which it will take over the host's duties. In this mode the host will no longer be significant in the game, lose access to the game's settings, and the server will control the settings instead. How exactly will it behave is then entirely up to the community that writes the "scripts" or whatever else will communicate via the API. It could be any of:
- GUI tool that will let people allowed to control the server do so via the provided GUI, outside of the game.
- A simple script that will force specific settings, monitor the events and change the track/vehicle class whenever players return back to the lobby. So a simple track/settings rotation.
- A script that would monitor chat from players, recognize special commands and act upon them. Players with specific IDs would be allowed to change some settings directly via the commands, non-privileged players could vote for settings changes.
- Much more complex app implementing an automatic league. It could implement persistent ranking of players, open the server with specific settings when the next league round starts, control who can join the race, archive positional status and various events for post-race review (we won't provide full replays automatically though), and so on.
Note that all of this is just the ideal goal, and up to the community to implement. We just plan to provide the tools to do so.
How to enable the HTTP API
By default the HTTP-based API is disabled. Please read the HowTo for the full list of available setup options.
To enable the API, change the enableHttpApi setting to true. By default the API will be then available via HTTP at 127.0.0.1:9000 . This can be reconfigured by the options httpApiInterface and httpApiPort .
API security
The HTTP API is running on a simple internal HTTP server based on the libwebsockets library. Only http access is enabled, there is no https support (at least not yet). The server also does not implement any other security features yet, there is no password/key-protected access to the API or IP blacklisting/whitelisting. Be aware of that when exposing the access to the API via the server settings. You might want to setup some kind of proxy based on Apache or anything else, and control the access at that level.
Or just limit it to the computer the server is running on (which is the default) or the local network where the server is hosted, with anything public "sitting behind" the scripts you implement on top of the API. So as a simple example, you could run the server on the same computer as your website, and write a simple PHP script that would access the server's status and present it in a pretty way on the web. And with some additional scripting, it could live-update the car status and display that. Without ever exposing the server's API itself to the public.
API usage
The API is a simple HTTP-based thingy, you run HTTP GET queries and it returns responses, mostly JSON-encoded. The JSON responses contain these fields:
- "result" - for now just "ok", but for some API calls the result could be something else. That will apply mostly to calls that request game changes.
- "message" - optional user friendly message
- "response" - JSON object with the actual data returned by the call
So as an example, assuming the DS is running on your local machine, you could query it with http://127.0.0.1:9000/api/session/st...s&participants . This returns JSON response with the full status, with all attributes of the session itself, as well as its members and participants. The middle of the response might look like this:
Code:{ "result" : "ok", "response" : { ... "attributes" : { ... "NumParticipantsDisqualified" : 0, "NumParticipantsRetired" : 0, "NumParticipantsDNF" : 0, "NumParticipantsFinished" : 0 }, "members" : [ { "index" : 0, "refid" : 19008, "steamid" : STEAMID_REMOVED, "state" : "Connected", "name" : "REMOVED", "jointime" : 1432039628, "host" : true, "attributes" : { "VehicleId" : 1023089804, "LiveryId" : 64, "LoadState" : "ADMIN_STARTED_RACE", "RaceStatFlags" : 1073797090, "Ping" : 53 } } ], "participants" : [ { "attributes" : { "RefId" : 19008, "Name" : "REMOVED", "IsPlayer" : 1, "GridPosition" : 1, "VehicleId" : 1023089804, "LiveryId" : 64, "RacePosition" : 1, "CurrentLap" : 0, ...
API - help
The endpoint /api/version will return server version details (build, protocol and Lua API).
The API provides automatically generated help at /api/help URL. This will return the list of all available methods implemented by the API, their parameters, result format and a short description.
Lists associated with the gameplay and the server data are available at /api/list and its various sub-calls. This can include the list of all session attributes, or track or vehicle lists.
(attributes and event descriptions have been implemented so far)
API - status
You can query the session status at /api/session/status. Without any query parameters it just returns basic data about the session, you can request all session attributes, member list and participant (car) list as well. For more information please check the /api/help.
API - events
In addition to current status snapshot the game also reports various events to the server. The server keeps certain amount of the events in its internal log, the size of the log can be configured in server.cfg, in setting eventsLogSize.
The events log is available via the API at /api/log:
- /api/log/overview: Returns the number of events stored in the log, and index of the oldest event.
- /api/log/range: Returns count of events from the logs, starting at index offset. You can use negative offset to request specify the offset relative to the end of the log, so "offset=-100&count=100" would return 100 most recent events. This call also returns the same info as the overview in addition to the events.
API - controlling the server
The control mode can be configured by these two variables:
- allowEmptyJoin: true - this is set to true by default, and will make the server appear in the session browser when it's empty. When someone joins an empty server, the game's setup will start with sessionAttributes, and the first member will become the session's host. When the game is not controlled be the server, the host will then be able to change this setup to anything else. Please refer to /api/list/attributes/session for the list of attributes that can be specified in sessionAttributes, only the ReadWrite or WriteOnly attributes can be set here.
- controlGameSetup: false - this is set to false by default. If changed to true, the server will take over the game's control. Such server must also have allowEmptyJoin set to true, because it will no longer be joinable via the command-line driven Create flow. When the server controls the game, the host will no longer be able to modify the game's setup in the lobby, instead the server's API can be used to do that.
Two session attributes fine-tune the game-controlling mode:
- ServerControlsTrack: If set to non-zero, the server takes over track selection in addition to the game's setup. The host will no longer be able to select the track.
- ServerControlsVehicle: If set to non-zero, the server takes over vehicle selection in addition to the game's setup. This is not fully implemented yet, so players will still be able to choose their cars even if this is set to true.
The control API itself is:
/api/session/set_next_attributes: This modifies "next session attributes". The initial values are set from the config file's sessionAttributes. "Next session attributes" are used when the first player joins an empty server - the game will start with these settings. In addition to that, if the server control's the game's attributes, these will be also applied to the lobby whenever a race is finished and the game loads to the lobby. So in short, if the server is not game controlling, this provides the defaults for empty servers, and if the server is game controlling, this can be also used to modify the setup of the next race, automatically applied when the current race finishes.
/api/session/set_attribtes: This API call is available only if the server is running in game controlling mode. It modifies the current game's setup while in the lobby.
/api/session/send_chat: While not directly used to control the game, this can be used to send chat texts to the game from the server. It can be used to welcome new lobby members and send some info about the server to them, or to notify them about any changes applied by the server.
The set_next_attributes and set_attributes have similar argument structure. But the set_next_attributes command can modify only the session attributes, none of the participant or player arguments will be used (note that the game currently does not define any modifiable player or participant attributes anyway)
- copy_to_next: Boolean optional argument to set_attributes. This will make any session attribute changes also modify the "next session attributes" list. It defaults to false but you will quite often want to use this, otherwise the set_attributes call modifies only the current lobby settings, and the next lobby will revert back to the "next session attributes". If the session is not in a lobby, then the set_attributes call will still succeed if this argument is set to true, and do the exact same thing as set_next_attributes (since there are not current lobby attributes to modify)
- refid: RefId of the player to modify if any player attributes are set
- participantid: Participant id of the participant to modify if any participant attributes are set
- session_NAME: Set value of session attribute NAME. See /api/list/attributes/session for the list of all valid attribute names and types. Only writable attributes can be set
- player_NAME: Set value of player attribute NAME. Currently no player attributes are writable
- participant_NAME: Set value of participant attribute NAME. Currently no participant attributes are writable
Example:
(assuming the default local server port is used)Code:http://127.0.0.1:9000/api/session/set_attributes?copy_to_next&session_Practice1Length=15&session_RaceLength=10&session_TrackId=1300627020
This will modify the current lobby and the next session attributes to use 15 minute practice 1 session, 10 laps, on Brands Hatch Indy
Status web
The internal server also hosts a simple web page at /status. This is similar to information provided by the /api/session/status as well as the event log, but formatted as a simple human-readable web page. It's intended mostly for debugging the server while developing the API, not as something to be made available to the public.
Documentation
Last updated 01.03.2016, latest PDF documents are always available in the server tool downloaded from Steam.
Game Guide: A simple short guide about joining the servers from the browser
GameGuide.pdf
User Guide: Server administration and setup information
UserGuide.pdf
Scripting Guide: All about Lua scripting
ScriptingGuide.pdf
Server Values and Types: Reference with various useful data types / lists: all attributes, events, id lists, enums, flags.
ServerTypes.pdf
Reply With Quote
Originally Posted by Stepan Vondrak
