Headless Client/Configuration File

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 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 event
• Neos.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 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	string	An optional custom session id for this session. S- is prefixed at runtime.	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.	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.	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	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 false, this will disable this world entry from starting. This is useful to turn worlds on or off.	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","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 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

SessionAccessLevel

SessionAccessLevel controls the access level of a session. Possible values are:

• Private
• LAN
• Friends
• FriendsOfFriends
• 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. 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"

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
• TODO

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.