Difference between revisions of "Headless Client/Configuration File"
Line 118: | Line 118: | ||
!Description | !Description | ||
! Required | ! Required | ||
+ | ! Example | ||
|- | |- | ||
|'''sessionName''' | |'''sessionName''' | ||
Line 123: | Line 124: | ||
|The name of the session as shown in the World/Session Browser | |The name of the session as shown in the World/Session Browser | ||
|No | |No | ||
+ | | "cheese" | ||
|- | |- | ||
|'''customSessionId''' | |'''customSessionId''' | ||
|<code>string</code>|An optional custom session id for this session. | |<code>string</code>|An optional custom session id for this session. | ||
|No | |No | ||
+ | |U-ProbablePrime:CheeseLand | ||
|- | |- | ||
|'''description''' | |'''description''' | ||
Line 132: | Line 135: | ||
|An optional description of this session, displayed within the world/session browser. | |An optional description of this session, displayed within the world/session browser. | ||
|No | |No | ||
+ | |The land of the cheese | ||
|- | |- | ||
|'''maxUsers''' | |'''maxUsers''' | ||
|<code>integer</code>|The maximum number of users, allowed to join this session. | |<code>integer</code>|The maximum number of users, allowed to join this session. | ||
|No, default: 32 | |No, default: 32 | ||
+ | | 42 | ||
|- | |- | ||
|'''accessLevel''' | |'''accessLevel''' | ||
|<code>any</code> | |<code>any</code> | ||
− | |The Access Level for this session please see SessionAccessLevel for more information. | + | |The Access Level for this session please see [[#SessionAccessLevel]] for more information. |
|No | |No | ||
+ | | Anyone | ||
|- | |- | ||
|'''hideFromPublicListing''' | |'''hideFromPublicListing''' | ||
Line 146: | Line 152: | ||
|Determines if this session should be hidden from the world/session browser or not. | |Determines if this session should be hidden from the world/session browser or not. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''tags''' | |'''tags''' | ||
Line 151: | Line 158: | ||
|A list of tags, to assist with searching or discovering sessions. | |A list of tags, to assist with searching or discovering sessions. | ||
|No | |No | ||
+ | |cheese,world,game | ||
|- | |- | ||
|'''mobileFriendly''' | |'''mobileFriendly''' | ||
Line 156: | Line 164: | ||
|Determines if this session is friendly for mobile/quest users. | |Determines if this session is friendly for mobile/quest users. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''loadWorldURL''' | |'''loadWorldURL''' | ||
Line 161: | Line 170: | ||
|When provided with a world URL this will load this world for the session. | |When provided with a world URL this will load this world for the session. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''loadWorldPresetName''' | |'''loadWorldPresetName''' | ||
Line 166: | Line 176: | ||
|When provided and valid, this will load the specified world preset into the session. | |When provided and valid, this will load the specified world preset into the session. | ||
|No | |No | ||
+ | |Space | ||
|- | |- | ||
|'''overrideCorrespondingWorldId''' | |'''overrideCorrespondingWorldId''' | ||
Line 171: | Line 182: | ||
|Overrides the world id for this session allowing it to be grouped and displayed with other sessions with this world id. | |Overrides the world id for this session allowing it to be grouped and displayed with other sessions with this world id. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''forcePort''' | |'''forcePort''' | ||
Line 176: | Line 188: | ||
|Optional, If specified it will force this session to run on a specific network port. | |Optional, If specified it will force this session to run on a specific network port. | ||
|No | |No | ||
+ | |4242 | ||
|- | |- | ||
|'''keepOriginalRoles''' | |'''keepOriginalRoles''' | ||
Line 181: | Line 194: | ||
|Optional, If specified will keep the original roles as saved in the world. | |Optional, If specified will keep the original roles as saved in the world. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''defaultUserRoles''' | |'''defaultUserRoles''' | ||
|<code>null,object</code> | |<code>null,object</code> | ||
− | |When provided with a list of username and permission pairs it will grant those users the listed permissions when they join. | + | |When provided with a list of username and permission pairs it will grant those users the listed permissions when they join. See [[#User Roles]] for more information. |
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''roleCloudVariable''' | |'''roleCloudVariable''' | ||
Line 191: | Line 206: | ||
|An optional name of a cloud variable to use to determine the role of this user. See [[Cloud Variables#Roles]] for more information. | |An optional name of a cloud variable to use to determine the role of this user. See [[Cloud Variables#Roles]] for more information. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''allowUserCloudVariable''' | |'''allowUserCloudVariable''' | ||
Line 196: | Line 212: | ||
|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. | |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 | |No | ||
+ | | | ||
|- | |- | ||
|'''denyUserCloudVariable''' | |'''denyUserCloudVariable''' | ||
Line 201: | Line 218: | ||
|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. | |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 | |No | ||
+ | | | ||
|- | |- | ||
|'''requiredUserJoinCloudVariable''' | |'''requiredUserJoinCloudVariable''' | ||
Line 206: | Line 224: | ||
|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. | |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 | |No | ||
+ | | | ||
|- | |- | ||
|'''requiredUserJoinCloudVariableDenyMessage''' | |'''requiredUserJoinCloudVariableDenyMessage''' | ||
Line 211: | Line 230: | ||
|The name of a cloud variable whose value will be used, When a user is denied access by RequiredUserJoinCloudVariable this message will be displayed to them if present. See [[Cloud Variables#Joining Control]] for more information. | |The name of a cloud variable whose value will be used, When a user is denied access by RequiredUserJoinCloudVariable this message will be displayed to them if present. See [[Cloud Variables#Joining Control]] for more information. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''awayKickMinutes''' | |'''awayKickMinutes''' | ||
Line 216: | Line 236: | ||
|Configures the number of minutes that a user can be away(shelled out) from a world before they are kicked. Setting this to -1 disables this option. | |Configures the number of minutes that a user can be away(shelled out) from a world before they are kicked. Setting this to -1 disables this option. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''isEnabled''' | |'''isEnabled''' | ||
Line 221: | Line 242: | ||
|When set to true, this will disable this world entry from starting. | |When set to true, this will disable this world entry from starting. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''saveAsOwner''' | |'''saveAsOwner''' | ||
|<code>any</code> | |<code>any</code> | ||
− | |Controls who saves this world when it is saved. See, SaveAsOwner for more information. | + | |Controls who saves this world when it is saved. See, [[#SaveAsOwner]] for more information. |
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''autoInviteUsernames''' | |'''autoInviteUsernames''' | ||
Line 231: | Line 254: | ||
|Users within this list will automatically be invited to this world when it starts. | |Users within this list will automatically be invited to this world when it starts. | ||
|No | |No | ||
+ | | ProablePrime,Frooxius | ||
|- | |- | ||
|'''parentSessionIds''' | |'''parentSessionIds''' | ||
|<code>array,null</code> | |<code>array,null</code> | ||
− | |Provides a list of Parent Session Ids for this session. See | + | |Provides a list of Parent Session Ids for this session. See [[Parent Sessions]] for more info. |
|No | |No | ||
|- | |- | ||
Line 241: | Line 265: | ||
|An automatic message sent to the users on the AutoInviteUsernames list along with their invite. | |An automatic message sent to the users on the AutoInviteUsernames list along with their invite. | ||
|No | |No | ||
+ | |Come and play! | ||
|- | |- | ||
|'''autoRecover''' | |'''autoRecover''' | ||
Line 246: | Line 271: | ||
| | | | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''idleRestartInterval''' | |'''idleRestartInterval''' | ||
Line 251: | Line 277: | ||
|If this is set(>0) and the world is empty, it will restart regularly using the value to determine the number of seconds between restarts. | |If this is set(>0) and the world is empty, it will restart regularly using the value to determine the number of seconds between restarts. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''forcedRestartInterval''' | |'''forcedRestartInterval''' | ||
Line 256: | Line 283: | ||
|If this is set(>0), it will restart regularly using the value to determine the number of seconds between restarts. | |If this is set(>0), it will restart regularly using the value to determine the number of seconds between restarts. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''saveOnExit''' | |'''saveOnExit''' | ||
Line 261: | Line 289: | ||
|If set to true will save this world on exit. | |If set to true will save this world on exit. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''autosaveInterval''' | |'''autosaveInterval''' | ||
Line 266: | Line 295: | ||
|If this is set(>0), it will automatically save using the value to determine the number of seconds between saves. | |If this is set(>0), it will automatically save using the value to determine the number of seconds between saves. | ||
|No | |No | ||
+ | | | ||
|- | |- | ||
|'''autoSleep''' | |'''autoSleep''' | ||
|<code>boolean</code> | |<code>boolean</code> | ||
− | |If set to true, will prevent an empty(or filled with away users) world from running a full update cycle | + | |If set to true, will prevent an empty(or filled with away users) world from running a full update cycle regularly. |
|No | |No | ||
|} | |} |
Revision as of 10:43, 24 October 2021
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
.
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 Neos.exe you can use the command line option -c
to specify a configuration file. This lets you maintain multiple configuration files for multiple projects or events. For example you could create and use:
Neos.exe -c Config/CoolConvention.json
- For a large Convention or eventNeos.exe -c 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
|
Neos username for this Headless Server to use. | ✓ Yes |
loginPassword | string
|
Neos user password for the Headless Server to use. | ✓ Yes |
startWorlds | See #Start Worlds | An array of worlds/sessions to start/create when this Headless Server starts. | ✓ Yes |
universeId | string
|
Optionally, specifies which universe this Headless Server will be in. See our wiki article on 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 Neos will use to store data for this Headless Server. | No |
cacheFolder | string
|
Optionally, override the folder which Neos will use to store cache for this Headless Server. | No |
logsFolder | tring
|
Optionally, override the folder which Neos will use to store logs for this Headless Server. | No |
allowedUrlHosts | string array
|
A list of hosts which will automatically be allowed for in-Neos HTTP/WebSocket operations | No |
autoSpawnItems | string array
|
A list of item URIs to spawn in when a world starts. | No |
metamovieRoles | object
|
Legacy content for the MetaMovie Project. Feel Free to ignore | No |
Start Worlds
Within the configuration file is an array called startWorlds
, this array is a list of worlds which should be started when the Headless Client starts. You can run as many worlds as you want on a single Headless Client. The format 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 | An optional custom session id for this session. | 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 | 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, 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. | No | |
loadWorldPresetName | null,string
|
When provided and valid, this will load the specified world preset into the session. | No | Space |
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. See #User Roles for more information. | No | |
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
|
The name of a cloud variable whose value will be used, When a user is denied access by RequiredUserJoinCloudVariable this message will be displayed to them if present. See Cloud Variables#Joining Control for more information. | No | |
awayKickMinutes | number
|
Configures the number of minutes that a user can be away(shelled out) from a world before they are kicked. Setting this to -1 disables this option. | No | |
isEnabled | boolean
|
When set to true, this will disable this world entry from starting. | No | |
saveAsOwner | any
|
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 | ProablePrime,Frooxius |
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 is empty, 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 on exit. | 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 |