Configuration

Compile and Run on Linux

Prerequisits Assuming Debian/Ubuntu

For Ubuntu 22.04, sudo add-apt-repository ppa:dotnet/backports

For Debian or other qurirky setups:

wget https://packages.microsoft.com/config/debian/12/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb
rm packages-microsoft-prod.deb

Then continue installation:

sudo apt-get update && sudo apt-get install -y dotnet-sdk-10.0

Get Basis

Change to the folder you wish to download Basis to, and execute the following command:

git clone -b long-term-support-20260425 https://github.com/BasisVR/Basis

Build Basis Server

Open a new terminal and cd /to/directory/with/Basis Server/, i.e. cd Basis/Basis\ Server

dotnet restore

Then build, with either:

dotnet build (for debug)

dotnet build --configuration Release (For release)

Executing

Navigate to the BasisServerConsole directory (Something like /BasisServerConsole/bin/Debug/net10.0/BasisNetworkConsole) and run:

dotnet .\BasisNetworkConsole.dll

:::tip For More Targeted Linux Release

You may compile with the following:

dotnet publish -f net10.0 --self-contained --os Linux

The --self-contained switch is added to allow running on a OS without dotnet installed.

If you compile via this method (Or your build targeted the system) are on a you should be able to run

./BasisNetworkConsole

from BasisServerConsole/bin/Debug/net10.0/BasisNetworkConsole.

:::

Firewall

You may want to open ports:

1234/tcp
10666/tcp
4296/udp

Configuration Files

The first time you run the server a variety of config files and structure will be created in the directory the server exe rests in.

File/Folder	Description
`config.xml`	Main configuration file for the server.
`initialresources/`	This directory contains world and object files the server will load upon request.
`Log/`	Folder where server logs are stored.
`admins.xml`	List of users with admin privileges.
`banned_players.xml`	List of banned player accounts.

Config.xml

Variable	Default	Description
`PeerLimit`	65535	Maximum number of connected peers.
`SetPort`	4296	UDP port the server listens on.
`UseNativeSockets`	true	Use OS-native socket calls instead of the managed path.
`NatPunchEnabled`	false	Enable NAT punch-through for peer introduction.
`PingInterval`	1500	Interval between keep-alive pings, in milliseconds.
`DisconnectTimeout`	30000	Time with no response before disconnecting a peer, in milliseconds.
`SimulatePacketLoss`	false	Artificially drop outgoing packets for testing.
`SimulateLatency`	false	Artificially delay packets for testing.
`SimulationPacketLossChance`	10	Packet-loss percentage when packet-loss simulation is enabled.
`SimulationMinLatency`	50	Minimum added latency, in milliseconds.
`SimulationMaxLatency`	150	Maximum added latency, in milliseconds.
`ReconnectDelay`	500	Time before attempting reconnect.
`MaxConnectAttempts`	10	Max number of reconnect attempts.
`ReuseAddresss`	false	Socket reuse option; note the field spelling.
`DontRoute`	false	Socket routing option.
`EnableStatistics`	true	Collect transport statistics for health/status reporting.
`IPv6Enabled`	true	Enable IPv6 dual-stack socket support.
`MtuOverride`	0	Force a fixed MTU; `0` disables override.
`MtuDiscovery`	true	Enable path-MTU discovery.
`DisconnectOnUnreachable`	false	Disconnect on ICMP unreachable.
`AllowPeerAddressChange`	true	Allow a peer endpoint to change mid-session.
`HasFileSupport`	true	Enables writing logs, moderation lists, auth identity data, and other disk-backed files.
`HealthCheckHost`	localhost	Host/interface used for health checks. Use `*` to bind to any interface.
`HealthCheckPort`	10666	TCP port used for health checks.
`HealthPath`	/health	Path to health check endpoint.
`BSRSMillisecondDefaultInterval`	50	Base send interval in milliseconds for the server reduction system.
`BSRBaseMultiplier`	1	Base multiplier applied before distance scaling.
`BSRSIncreaseRate`	0.005	How quickly send intervals grow with distance.
`BSRSlowestSendRate`	2.55	Slowest send-rate floor handed to clients for distant peers.
`HighQualityDistance`	3	Distance threshold for high-quality avatar sync.
`MediumQualityDistance`	10	Distance threshold for medium-quality avatar sync.
`LowQualityDistance`	20	Distance threshold for low-quality avatar sync.
`OverrideAutoDiscoveryOfIpv`	false	Bind exactly the configured addresses instead of auto-discovering IP version.
`IPv4Address`	0.0.0.0	IPv4 bind address.
`IPv6Address`	::	IPv6 bind address.
`Password`	default_password	Server access password.
`UseAuth`	true	Enable or disable password authentication.
`UseAuthIdentity`	true	Require DID identity verification when auth is enabled.
`BasisUserRestrictionMode`	Normal	Player join restriction mode: `Normal`, `BlackList`, or `WhiteList`.
`HowManyDuplicateAuthCanExist`	2	Number of simultaneous connections allowed for the same auth identity.
`AuthValidationTimeOutMiliseconds`	9000	Timeout for auth validation, in milliseconds.
`EnableConsole`	true	Enable the interactive server console.
`DisableWriteUnlessAdminPersistentFlag`	true	Reject persistent key/value writes unless the caller is an admin.
`DisableReadUnlessAdminPersistentFlag`	false	Reject persistent key/value reads unless the caller is an admin.
`UseNetworkFinalCompression`	false	Enable final network compression pass.
`EnableBSRProfiling`	false	Emit server reduction system profiling output.
`DisallowHeadless`	false	Reject headless clients from connecting.
`AvatarsLocked`	false	Block avatar loading for users without bypass permission.
`PropsLocked`	false	Block prop loading for users without bypass permission.
`WorldsLocked`	true	Block world loading for users without bypass permission.

Any environment variable whose name matches a public config field overrides that field at launch.

Authentication Settings

<UseAuth>true</UseAuth>

Meant to be used for turning off auth all together.

<UseAuthIdentity>true</UseAuthIdentity>

Enables disable DID auth provider.

<BasisUserRestrictionMode>Normal</BasisUserRestrictionMode>

Not finished yet. Admin moderation.

<HowManyDuplicateAuthCanExist>2</HowManyDuplicateAuthCanExist>

How many people can connect with the same Auth credentials.

Example Config.xml

The default settings you may find in the config.xml:

config.xml

<?xml version="1.0" encoding="utf-8"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <PeerLimit>65535</PeerLimit>
  <SetPort>4296</SetPort>
  <UseNativeSockets>true</UseNativeSockets>
  <NatPunchEnabled>false</NatPunchEnabled>
  <PingInterval>1500</PingInterval>
  <DisconnectTimeout>30000</DisconnectTimeout>
  <SimulatePacketLoss>false</SimulatePacketLoss>
  <SimulateLatency>false</SimulateLatency>
  <SimulationPacketLossChance>10</SimulationPacketLossChance>
  <SimulationMinLatency>50</SimulationMinLatency>
  <SimulationMaxLatency>150</SimulationMaxLatency>
  <ReconnectDelay>500</ReconnectDelay>
  <MaxConnectAttempts>10</MaxConnectAttempts>
  <ReuseAddresss>false</ReuseAddresss>
  <DontRoute>false</DontRoute>
  <EnableStatistics>true</EnableStatistics>
  <IPv6Enabled>true</IPv6Enabled>
  <MtuOverride>0</MtuOverride>
  <MtuDiscovery>true</MtuDiscovery>
  <DisconnectOnUnreachable>false</DisconnectOnUnreachable>
  <AllowPeerAddressChange>true</AllowPeerAddressChange>
  <HasFileSupport>true</HasFileSupport>
  <HealthCheckHost>localhost</HealthCheckHost>
  <HealthCheckPort>10666</HealthCheckPort>
  <HealthPath>/health</HealthPath>
  <BSRSMillisecondDefaultInterval>50</BSRSMillisecondDefaultInterval>
  <BSRBaseMultiplier>1</BSRBaseMultiplier>
  <BSRSIncreaseRate>0.005</BSRSIncreaseRate>
  <BSRSlowestSendRate>2.55</BSRSlowestSendRate>
  <HighQualityDistance>3</HighQualityDistance>
  <MediumQualityDistance>10</MediumQualityDistance>
  <LowQualityDistance>20</LowQualityDistance>
  <OverrideAutoDiscoveryOfIpv>false</OverrideAutoDiscoveryOfIpv>
  <IPv4Address>0.0.0.0</IPv4Address>
  <IPv6Address>::</IPv6Address>
  <Password>default_password</Password>
  <UseAuth>true</UseAuth>
  <UseAuthIdentity>true</UseAuthIdentity>
  <BasisUserRestrictionMode>Normal</BasisUserRestrictionMode>
  <HowManyDuplicateAuthCanExist>2</HowManyDuplicateAuthCanExist>
  <AuthValidationTimeOutMiliseconds>9000</AuthValidationTimeOutMiliseconds>
  <EnableConsole>true</EnableConsole>
  <DisableWriteUnlessAdminPersistentFlag>true</DisableWriteUnlessAdminPersistentFlag>
  <DisableReadUnlessAdminPersistentFlag>false</DisableReadUnlessAdminPersistentFlag>
  <UseNetworkFinalCompression>false</UseNetworkFinalCompression>
  <EnableBSRProfiling>false</EnableBSRProfiling>
  <DisallowHeadless>false</DisallowHeadless>
  <AvatarsLocked>false</AvatarsLocked>
  <PropsLocked>false</PropsLocked>
  <WorldsLocked>true</WorldsLocked>
</Configuration>

Loadable Configuration Files

You may setup world and object files to load on demand. These are the files you place in the InitialResources folder.

Note that the remote urls you use must be served from a proper server that supports chunking. Any modern server should do this but simple local dev servers may not.

To upload something

One avenue you can use to test out a new scene is to create a scene in Unity, export the scene as a BEE file. Upload that BEE file to a server that supports HTTP, then, place the URL in CombinedURL, and get the password from dontuploadmepassword.txt and place it in UnlockPassword.

Variable	Definition
`Mode`	Mode of the configuration: `0` = Game object, `1` = Scene.
`LoadedNetID`	A Network ID: Server keeps a list of Network Objects that Clients can query and spawn with this value as a reference.
`UnlockPassword`	Password required to unlock or access the resource.
`CombinedURL`	URL to the `.BEE` file
`IsLocalLoad`	Indicates whether the resource is loaded locally (`true`) or from the internet (`false`).
`PositionX`	X-axis world position of the object.
`PositionY`	Y-axis world position of the object.
`PositionZ`	Z-axis world position of the object.
`QuaternionX`	X component of the object's rotation (quaternion).
`QuaternionY`	Y component of the object's rotation (quaternion).
`QuaternionZ`	Z component of the object's rotation (quaternion).
`QuaternionW`	W component of the object's rotation (quaternion).
`ScaleX`	X-axis scale factor.
`ScaleY`	Y-axis scale factor.
`ScaleZ`	Z-axis scale factor.
`Persist`	If the player that spawned the object leaves the server does the object continue to exist?

Example Configuration

BasisLoadableConfiguration Example

<BasisLoadableConfiguration>

    <!-- Mode of the configuration: Mode  0 = Game object, 1 = Scene -->
    <Mode>0</Mode>

    <!-- A Network ID: Server keeps a list of Network Objects that Clients can query and spawn with this value. -->
    <LoadedNetID></LoadedNetID>

    <!-- Unlock password -->
    <UnlockPassword>ffee4439eff</UnlockPassword>

    <!-- Combined URL link to BEE file -->
    <CombinedURL>https://www.example.com/2lkj23j.BEE</CombinedURL>

    <!-- Does this resource exist on the internet or in the client? -->
    <IsLocalLoad>false</IsLocalLoad>

    <!-- Position values -->
    <PositionX>0</PositionX>
    <PositionY>0</PositionY>
    <PositionZ>0</PositionZ>

    <!-- Quaternion values -->
    <QuaternionX>0</QuaternionX>
    <QuaternionY>0</QuaternionY>
    <QuaternionZ>0</QuaternionZ>
    <QuaternionW>1</QuaternionW>

    <!-- Scale values -->
    <ScaleX>1</ScaleX>
    <ScaleY>1</ScaleY>
    <ScaleZ>1</ScaleZ>

    <!--  If the player that spawned the object leaves the server does the object continue to exist?  -->
    <Persist>false</Persist>

</BasisLoadableConfiguration>

*/}

On this page