Skip to content

Commit 4ba98b4

Browse files
johnprobablejohnprobable
committed
initial release for SpatialOS 11.0.0
1 parent bd60847 commit 4ba98b4

26 files changed

+1512
-2
lines changed

‎.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# SpatialOS project build directory
2+
build/
3+
4+
# Cache and other project metadata
5+
.spatialos/
6+
7+
# Logs
8+
spatial.log
9+
logs/
10+
11+
# Schema generated code
12+
generated_code
13+
14+
# Worker SDK and other dependencies
15+
dependencies/
16+
17+
# Visual Studio output directories and temporary files
18+
bin
19+
obj
20+
.vs
21+
*.user

‎README.md‎

Lines changed: 196 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,196 @@
1-
# CsharpBlankProject
2-
This is a SpatialOS project which can serve as a template for building SpatialOS workers using the C# SDK.
1+
# SpatialOS C# Blank project
2+
3+
## Quick start
4+
5+
Build the project and start it with the default launch configuration:
6+
```
7+
spatial worker build
8+
spatial local launch
9+
```
10+
11+
Connects a new instance of the C# External worker to a running local
12+
deployment.
13+
```
14+
spatial local worker launch External local
15+
```
16+
17+
See sections below for more details.
18+
19+
## Troubleshooting
20+
21+
If you encounter any errors when trying to build or launch this project,
22+
firstly make sure that all the dependencies of SpatialOS are met by running
23+
`spatial diagnose`.
24+
25+
Warnings about missing files from `msbuild` during `spatial worker build` might
26+
mean you don't have the required C++ build tools in your installation of
27+
`msbuild` if it came with Visual Studio. You will need to modify your
28+
installation of Visual Studio to include [C++ build
29+
tools](http://landinghub.visualstudio.com /visual-cpp-build-tools).
30+
31+
Visual Studio has a weird way to pick default configuration and platform for
32+
builds. Because of that the default configuration when you open one of the
33+
solutions for the first time in Visual Studio will be `DebugLinux`. This might
34+
cause build errors on other platforms so use the dropdown in Visual Studio to
35+
select a configuration matching your platform.
36+
37+
In case you need further assistance, don't hesitate to ask on the
38+
[forums](https://forums.improbable.io/c/sup/setup-and-tutorials) and remember
39+
to attach the contents of your `logs` folder and output from the failing
40+
commands.
41+
42+
## Build
43+
44+
Use `spatial worker build` as usual.
45+
46+
The current worker configuration is using a modified version of the generated
47+
`spatialos.csharp.build.json` which replaces `xbuild` with `msbuild` and adds
48+
some extra steps. On old versions of Mono (before 5.0.0), even though it's best
49+
to just update, you might want to replace `msbuild` with `xbuild`.
50+
51+
## Local launch
52+
53+
Use `spatial local launch` as usual.
54+
55+
Once the deloyment is running you can connect a worker with:
56+
57+
```
58+
spatial local worker launch External local
59+
```
60+
61+
`local` is an external launch configuration defined in
62+
`spatialos.External.worker.json`. Feel free to change it or add more
63+
configurations for different starting conditions.
64+
65+
When a worker connects the terminal which runs `spatial local launch` should
66+
output several messages:
67+
68+
The first two confirm that the connection is successful.
69+
```sh
70+
[improbable.bridge.oracle.service.BridgeOracleInternalServiceImpl] The worker ExternalLocalWindows registered with SpatialOS successfully.
71+
72+
[improbable.bridge.logging.EngineLogMessageHandler] [Worker: ExternalLocalWindows] Successfully connected using the Receptionist -[WorkerLogger:Startup.cs]
73+
```
74+
75+
You could also have configurations which start multiple workers or start
76+
workers directly from an executable. Look at [External worker launch configuration](https://docs.improbable.io/reference/latest/workers/configuration/launch-configuration) for all the technical details.
77+
78+
## Attaching a debugger
79+
80+
The easiest option is using Visual Studio. Open the project properties and set
81+
the command-line arguments in `Debug > Start options` to something like
82+
`receptionist localhost 7777 ExternalDebug`. Then you can start the project
83+
from Visual Studio. If you're using another IDE there must be a similar way to
84+
configure and start the project with a visual debugger.
85+
86+
## Project structure
87+
88+
The C# workers which come with this project are called _External_ and _Managed_
89+
to reflect the way they are configured and connected and their intended use as
90+
an external worker which is often used to implement a game client or a managed
91+
worker used for various tasks ranging from physics simulation to player login
92+
to inventory management and microservices. Have a look at the [Glossary entry
93+
for Workers](https://docs.improbable.io/reference/latest/getting-started/concepts/glossary#worker) for a quick intro and links to learning
94+
resources.
95+
96+
If you're building your own worker out of them, you're strongly encouraged to
97+
replace the names with something meaningful for your use case. A simple Find
98+
and Replace in both file contents and file names of the text "External" is
99+
sufficient to rename the worker named "External" and keep the convention to use
100+
the worker name in project files and build targets.
101+
102+
```
103+
+-- schema/
104+
+-- generated_code/csharp/
105+
+-- dependencies/worker_sdk
106+
+-- workers
107+
|-- External/
108+
| |-- External/
109+
| |-- BuildTargets.targets
110+
| |-- External.targets
111+
| |-- External.csproj
112+
| |-- GeneratedCode.csproj
113+
| |-- External.sln
114+
| |-- spatialos.External.worker.json
115+
| |-- spatialos_worker_packages.json
116+
| |-- spatialos.csharp_msbuild.build.json
117+
|
118+
|-- Managed/
119+
|-- Managed/
120+
|-- BuildTargets.targets
121+
|-- Managed.targets
122+
|-- Managed.csproj
123+
|-- GeneratedCode.csproj
124+
|-- Managed.sln
125+
|-- spatialos.Managed.worker.json
126+
|-- spatialos_worker_packages.json
127+
|-- spatialos.csharp_msbuild.build.json
128+
```
129+
130+
The SpatialOS C# Blank project contains two Visual Studio solutions each with
131+
several C# projects.
132+
133+
- `workers/External/External.sln` contains:
134+
- `External.csproj` with the worker sources
135+
- `GeneratedCode.csproj` with C# classes generated from schema sources
136+
137+
- `workers/Managed/Managed.sln` follows the same structure as described for
138+
`External`.
139+
140+
### More about the worker project structure
141+
142+
The worker project `External.csproj` has its sources located in
143+
`workers/External/External`, dependencies located in `dependencies/worker_sdk`,
144+
and build targets for all platforms located in two places:
145+
146+
- `workers/External/External/bin/x64` for the worker executables
147+
- `build/assembly/worker/External` for the packaged worker zips used by SpatialOS deployments
148+
149+
The `GeneratedCode.csproj` has its sources located in `generated_code/csharp`,
150+
dependencies located also in `dependencies/worker_sdk`, and builds a
151+
`GeneratedCode.dll` assembly for each configuration located in
152+
`workers/External/External/bin/generated_code` and referenced by the worker
153+
project.
154+
155+
### Why isn't there a single `GeneratedCode.csproj` shared by both solutions?
156+
157+
This might seem reasonable with the current state of the project since all C#
158+
generated code is included in both projects. However, it's good to have the
159+
flexibility to include only the code which is actually referenced by the worker
160+
project. This results in smaller assemblies and faster build times when large
161+
schemas are present.
162+
163+
## Cloud deployment
164+
165+
As usual set the `project_name` field in `spatialos.json` to match your SpatialOS project name. Then upload and launch:
166+
167+
```
168+
spatial cloud upload <AssemblyName>
169+
spatial cloud launch <AssemblyName> default_launch.json <deploymentname>
170+
```
171+
172+
However, the launcher doesn't support using C# workers to start clients yet. You can still connect a client to the deployment by obtaining a login token from the launcher and passing it when starting the `cloud` worker external configuration.
173+
174+
```
175+
spatial local worker launch External cloud <deploymentname> <login_token>
176+
```
177+
178+
## Cross-platform builds
179+
180+
With the current build configuration for workers (defined in
181+
`spatialos.csharp_msbuild.build.json`) running `spatial worker build` builds the
182+
release configurations for each of the 3 supported platforms. You can build for
183+
a specific platform only by passing the `target` flag:
184+
185+
```
186+
spatial worker build --target=ReleaseWindows
187+
```
188+
189+
This will skip all steps which have a target defined that is different from
190+
"ReleaseWindows". The target string is case-insensitive.
191+
192+
If you want to be able to build the Debug configurations with `spatial` from
193+
the command-line, it's easy to add more steps and define the respective
194+
targets. You can already build and run all Debug configurations which are
195+
defined for the projects from Visual Studio or by using `msbuild` on the
196+
command-line.

‎default_launch.json‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
{
2+
"template": "small",
3+
"world": {
4+
"chunkEdgeLengthMeters": 50,
5+
"snapshots": {
6+
"snapshotWritePeriodSeconds": 0
7+
},
8+
"dimensions": {
9+
"xMeters": 1500,
10+
"zMeters": 1500
11+
}
12+
},
13+
"workers": [
14+
{
15+
"worker_type": "External",
16+
"permissions": [{
17+
"entity_creation": {
18+
"allow": false
19+
},
20+
"entity_deletion": {
21+
"allow": false
22+
},
23+
"entity_query": {
24+
"allow": true,
25+
"components": []
26+
}
27+
}]
28+
},
29+
{
30+
"worker_type": "Managed",
31+
"permissions": [{
32+
"entity_creation": {
33+
"allow": false
34+
},
35+
"entity_deletion": {
36+
"allow": false
37+
},
38+
"entity_query": {
39+
"allow": true,
40+
"components": []
41+
}
42+
}],
43+
"load_balancing": {
44+
"auto_hex_grid": {
45+
"num_workers": 1
46+
}
47+
}
48+
}
49+
]
50+
}

‎schema/README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Schema
2+
3+
This is the root directory for user-defined schema files.

‎snapshots/default.snapshot‎

164 Bytes
Binary file not shown.

‎spatialos.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"name": "your_project_name_here",
3+
"project_version": "1.0.0",
4+
"sdk_version": "11.0.0",
5+
"dependencies": [
6+
{"name": "standard_library", "version": "11.0.0"}
7+
]
8+
}

‎workers/External/.gitignore‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
bin
2+
obj
3+
package
4+
.vs
5+
.spatialos
6+
*.user
7+
8+
# C# worker auto-generated project files
9+
spatialos.csharp.build.json
10+
11+
# These are commented out because it's not using auto-generated scripts
12+
# BuildTargets.targets
13+
# External.sln
14+
# External.targets
15+
# GeneratedCode.csproj

‎workers/External/BuildTargets.targets‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
2+
<PropertyGroup>
3+
<Prefer32Bit>false</Prefer32Bit>
4+
</PropertyGroup>
5+
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'DebugWindows|x64'">
6+
<OutputPath>bin\x64\DebugWindows\</OutputPath>
7+
<PackagePath>package\x64\DebugWindows\</PackagePath>
8+
<WorkerPlatform>windows</WorkerPlatform>
9+
</PropertyGroup>
10+
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'DebugMacOS|x64'">
11+
<OutputPath>bin\x64\DebugMacOS\</OutputPath>
12+
<PackagePath>package\x64\DebugMacOS\</PackagePath>
13+
<WorkerPlatform>darwin</WorkerPlatform>
14+
</PropertyGroup>
15+
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'DebugLinux|x64'">
16+
<OutputPath>bin\x64\DebugLinux\</OutputPath>
17+
<PackagePath>package\x64\DebugLinux\</PackagePath>
18+
<WorkerPlatform>linux</WorkerPlatform>
19+
</PropertyGroup>
20+
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'ReleaseWindows|x64'">
21+
<OutputPath>bin\x64\ReleaseWindows\</OutputPath>
22+
<PackagePath>package\x64\ReleaseWindows\</PackagePath>
23+
<WorkerPlatform>windows</WorkerPlatform>
24+
</PropertyGroup>
25+
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'ReleaseMacOS|x64'">
26+
<OutputPath>bin\x64\ReleaseMacOS\</OutputPath>
27+
<PackagePath>package\x64\ReleaseMacOS\</PackagePath>
28+
<WorkerPlatform>darwin</WorkerPlatform>
29+
</PropertyGroup>
30+
<PropertyGroup Condition="'$(Configuration)|$(Platform)' == 'ReleaseLinux|x64'">
31+
<OutputPath>bin\x64\ReleaseLinux\</OutputPath>
32+
<PackagePath>package\x64\ReleaseLinux\</PackagePath>
33+
<WorkerPlatform>linux</WorkerPlatform>
34+
</PropertyGroup>
35+
</Project>

‎workers/External/External.csproj‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<Project ToolsVersion="12.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
3+
<!-- Note that order of imports of targets is important and should be preserved.
4+
In particular, BuildTargets.targets should be imported before Microsoft.Csharp.targets.
5+
-->
6+
<Import Project="BuildTargets.targets" />
7+
<PropertyGroup>
8+
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
9+
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
10+
<ProjectGuid>{5F743C5A-5961-4406-83A9-3D97CB5FE4ED}</ProjectGuid>
11+
<OutputType>Exe</OutputType>
12+
<AssemblyName>External</AssemblyName>
13+
<TargetFrameworkVersion>v4.5.2</TargetFrameworkVersion>
14+
<FileAlignment>512</FileAlignment>
15+
<TargetFrameworkProfile />
16+
</PropertyGroup>
17+
<PropertyGroup>
18+
<StartupObject>External.Startup</StartupObject>
19+
</PropertyGroup>
20+
<ItemGroup>
21+
<Reference Include="System" />
22+
<Reference Include="System.Core" />
23+
<Reference Include="System.Xml" />
24+
</ItemGroup>
25+
<ItemGroup>
26+
<Compile Include="External\Startup.cs" />
27+
</ItemGroup>
28+
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
29+
<Import Project="External.targets" />
30+
</Project>

0 commit comments

Comments
 (0)