Server

ASP.NET Core server providing a network interface to the core library.

Config

Use appsettings.json to configure the server. You can also use Properties/launchSettings.json to easily run it with some IDEs. Command line args are accepted too.

The config params in appsettings.json are under Server. Following options are available:

  • Port - the port to use for the HTTPS/1 and HTTPS/2 endpoints (gRPC and REST), default 5001
  • PortHttp - the port to use for a cleartext HTTP/2 h2c gRPC endpoint, default 5000. Only used in development.
  • Seed - seed to use for terrain gen
  • Threads - maximum number of threads to use for parallel generation

See ServerOptions for details.

Only the gRPC endpoint runs, in addition, on the HTTP endpoint (at PortHttp) and only in development.
Every other endpoint runs on the main HTTPS endpoint (gRPC is running on both of them).

The links to endpoint in the document all use the default Port (5001), mind that if you have changed it.

gRPC

An gRPC endpoint is the main endpoint, providing the best performance and easy deserialization. This is used by the built in Unity client.

For ease of development, a HTTP/2 cleartext (h2c) endpoint is provided in dev mode. Other than that, gRPC run on HTTP/2 with TLS.

See the Protobuf Contracts and the generated classes to get a better idea on how to write your own gRPC client/ server.

REST API

A REST API endpoint is also provided by the server.

When you start the server, the OpenAPI swagger docs are served at /swagger. You can also view the raw OpenAPI spec at /swagger/v1/swagger.json.

For now, the following endpoints are provided:

  • /api/chunk/{x}/{y} - GET the chunk at coordinates (x, y). The chunk is serialized to JSON (the heightmap and materials are base64 encoded) along with some helpful data.
  • /view/chunk/{x}/{y} - GET an image preview of the chunk at coordinates (x, y). The image is in the webp format.

gRPC JSON transcoding

JSON transcoding is enabled for the gRPC endpoint. You can thus also view the gRPC endpoint transcoded to JSON at /v1/chunk/{x}/{y} (again, only on the HTTPS port).