Headless Clients have a lot of configuration potential. To achieve this a configuration file is used. Configuration files are written in JSON.
Default Configuration File
A default configuration file can be found within the Headless Client installation directory's Config subdirectory. It is named DefaultConfig.json. If the file does not exist then run the headless to generate it.
Creating your own Configuration File
To get started configuring things, copy the DefaultConfig.json file to a new file called Config.json. This will be automatically picked up when you run a Headless Client. Once copied we recommend editing the comment property to be something which describes the function of this file. Its value from the default file is incorrect so give it a comment which reflects what you intend to use it with.
After this you can proceed to edit your configuration file, following the Configuration File Format.
Using multiple configuration files
When running Resonite.exe you can use the command line option -HeadlessConfig to specify a configuration file. This lets you maintain multiple configuration files for multiple projects or events. For example you could create and use:
Resonite.exe -HeadlessConfig Config/CoolConvention.json- For a large Convention or eventResonite.exe -HeadlessConfig Config/SeriousBusinessMeeting.json- For a very serious business meeting.
It's up to you but feel free to write and use as many files as you'd like.
File Format
The headless configuration file has a lot of options and most of them are optional.
| Name | Type | Description | Required |
|---|---|---|---|
| comment | string
|
An optional free form comment for this file. Used for identification for your configuration. | No |
| loginCredential | string
|
Resonite username for this Headless Server to use. | No |
| loginPassword | string
|
Resonite user password for the Headless Server to use. | No |
| startWorlds | See #Start Worlds | An array of worlds/sessions to start/create when this Headless Server starts. | ✓ Yes (cannot be null) |
| universeId | string
|
Optionally, specifies which universe this Headless Server will be in. See Universes for more info. | No |
| tickRate | number
|
Configures how many ticks(updates), should occur per second. Default is 60. | No |
| maxConcurrentAssetTransfers | integer
|
Specifies the maximum concurrent asset transfers for this headless server. Default is 4. | No |
| usernameOverride | string
|
Configures a username which will override LoginCredential, within the world browser etc. | No |
| dataFolder | string
|
Optionally, override the folder which Resonite will use to store data for this Headless Server. | No |
| cacheFolder | string
|
Optionally, override the folder which Resonite will use to store caches for this Headless Server. | No |
| logsFolder | string
|
Optionally, override the folder which Resonite will use to store logs for this Headless Server. | No |
| allowedUrlHosts | string array
|
A list of hosts which will automatically be allowed for in-Resonite HTTP/WebSocket operations | No |
| autoSpawnItems | string array
|
A list of item URIs to spawn in when a world starts. | No |
Start Worlds
Within the configuration file is an array called startWorlds, this is a list of worlds which should be started automatically when the Headless Client starts. You can run as many worlds as you want on a single Headless Client. The headless will not automatically start any worlds if you leave the array empty. The format of this option is as follows:
...
"startWorlds":[
{
...world 1 config
},
{
...world 2 config
}
]
...
With each start world having the following properties:
| Name | Type | Description | Required | Example |
|---|---|---|---|---|
| sessionName | null,string
|
The name of the session as shown in the World/Session Browser | No | "cheese" |
| customSessionId | string
|
An optional custom session id for this session. S- is prefixed at runtime. This should be in the format of <UserID>:<Custom Id>. For more information see Custom Session IDs.
|
No | U-ProbablePrime:CheeseLand |
| description | string
|
An optional description of this session, displayed within the world/session browser. | No | The land of the cheese |
| maxUsers | integer
|
The maximum number of users, allowed to join this session. | No, default: 32 | 42 |
| accessLevel | any
|
The Access Level for this session please see #SessionAccessLevel for more information. | No | Anyone |
| hideFromPublicListing | boolean,null
|
Determines if this session should be hidden from the world/session browser or not. | No | |
| tags | array,null
|
A list of tags in the form of a JSON String array, to assist with searching or discovering sessions. | No | ["cheese","world","game"] |
| mobileFriendly | boolean
|
Determines if this session is friendly for mobile/quest users. | No | |
| loadWorldURL | null,string
|
When provided with a world URL this will load this world for the session. Use URLs that start with resrec:///. Use the "Copy record URL" button in the world browser to get it.
|
No | resrec:///U-ProbablePrime/R-ABC123-CHEESE-MOOO
|
| loadWorldPresetName | null,string
|
When provided and valid, this will load the specified world preset into the session. | No | Grid |
| overrideCorrespondingWorldId | any
|
Overrides the world id for this session allowing it to be grouped and displayed with other sessions with this world id. | No | |
| forcePort | integer,null
|
Optional, If specified it will force this session to run on a specific network port. | No | 4242 |
| keepOriginalRoles | boolean
|
Optional, If specified will keep the original roles as saved in the world. | No | |
| defaultUserRoles | null,object
|
When provided with a list of username and permission pairs it will grant those users the listed permissions when they join. | No | { "ProbablePrime":"Admin", "Frooxius":"Guest" } |
| roleCloudVariable | null,string
|
An optional name of a cloud variable to use to determine the role of this user. See Cloud Variables#Roles for more information. | No | |
| allowUserCloudVariable | null,string
|
An optional name of a cloud variable to use to determine if this user is allowed in the session. See Cloud Variables#Allowing User's Access for more information. | No | |
| denyUserCloudVariable | null,string
|
An optional name of a cloud variable to use to determine if this user is denied access to the session. See Cloud Variables#Denying User's Access for more information. | No | |
| requiredUserJoinCloudVariable | null,string
|
An optional name of a cloud variable to use to determine if this user is denied access to the session. See Cloud Variables#Joining Control for more information. | No | |
| requiredUserJoinCloudVariableDenyMessage | null,string
|
A message that is displayed when a user is denied access by RequiredUserJoinCloudVariable. See Cloud Variables#Joining Control for more information. | No | |
| useCustomJoinVerifier | boolean
|
When set to true, the VerifyJoinRequest ProtoFlux Node will be used in place of default session access rules. | No | |
| awayKickMinutes | number
|
Configures the number of minutes that a user can be away from a world (not focused) before they are kicked. Setting this to -1 disables this option. | No | |
| isEnabled | boolean
|
When set to false, this will disable this world entry from starting. This is useful to turn worlds on or off. | No | |
| saveAsOwner | string
|
Controls who saves this world when it is saved. See, #SaveAsOwner for more information. | No | |
| autoInviteUsernames | array,null
|
Users within this list will automatically be invited to this world when it starts. | No | ["ProbablePrime","Frooxius","kazzypoof"] |
| parentSessionIds | array,null
|
Provides a list of Parent Session Ids for this session. See Parent Sessions for more info. | No | |
| autoInviteMessage | null,string
|
An automatic message sent to the users on the AutoInviteUsernames list along with their invite. | No | Come and play! |
| autoRecover | boolean
|
No | ||
| idleRestartInterval | number
|
If this is set(>0) and the world has no users in it, it will restart regularly using the value to determine the number of seconds between restarts. | No | |
| forcedRestartInterval | number
|
If this is set(>0), it will restart regularly using the value to determine the number of seconds between restarts. | No | |
| saveOnExit | boolean
|
If set to true will save this world when shutting down the headless client. | No | |
| autosaveInterval | number
|
If this is set(>0), it will automatically save using the value to determine the number of seconds between saves. | No | |
| autoSleep | boolean
|
If set to true, will prevent an empty(or filled with away users) world from running a full update cycle regularly. | No |
SessionAccessLevel
SessionAccessLevel controls the access level of a session. Possible values are:
- Private
- LAN
- Contacts
- ContactsPlus
- RegisteredUsers
- Anyone
These match the regular session access levels you'll see in game.
SaveAsOwner
Save as owner controls how Headless Clients save the worlds that they are running.
Any value other than null is analogous to the "Save As..." option in the "Session" tab of the Dash menu, and will create a new record on each save.
Possible values are:
- LocalMachine - Saves the world as the Local Machine.
- CloudUser - Saves the world as the Cloud user who is logged in via the "login credentials"
- null - Attempts to save the world to the location it was loaded from, Analogous to the "Save Changes" option in the "Session" tab.
This should be null most of the time unless you want to create a brand new record for the world, such as when you are running a world that has not been saved on the headless before.
Example Files
We understand how these config files may seem daunting so we've prepared some example files:
- Headless Client/Example Configurations#Default - The default configuration file from the installation
- Headless Client/Example Configurations#Minimal - The Most minimal config
- Headless Client/Example Configurations#Minimal_with_Login - The Most minimal config with a user login
JSON Schemas
For Headless Client configuration files we are experimenting with JSON Schemas. JSON Schemas are files which describe the layout and schema of a JSON file. You can use them to Generate Code, Validate JSON etc. When editing configuration files in supported editors your configuration file will be automatically validated for errors etc.
See our repository of Schemas for more information.
Startup Configuration File
The Headless Server Software is also compatible with the Startup Config File, you can use all of the settings within it to also control aspects of the Headless Server Software. To do this, just follow the instructions on the Startup Config File page.
Do keep in mind that as a Headless Session does not have a renderer, some settings options may not be applicable.
A good example of one of the reasons you might take this approach is to handle Proxy Settings.
In the future, we may combine these two files into a more generic version that includes both settings as we understand that this might be confusing.