Space Station 14

https://docs.spacestation14.com
Admin
Space Station 14 is a multiplayer game about maintaining a space station, featuring robust gameplay...
Tokens:331,149
Snippets:892
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Guide Entry Prototype Example

Source: https://docs.spacestation14.com/en/general-development/tips/writing-guidebook-entries

This example demonstrates the structure of a guide entry prototype, which is used to display content within the Spacestation 14 guidebook. It includes fields for unique ID, display name, content file path, sorting priority, and child entries.

```yaml
- type: guideEntry
  id: Magboots
  name: guide-entry-magboots
  text: "/ServerInfo/Guidebook/magboots.xml"
  priority: 10
  children:
  - Radio

```

--------------------------------

### Install LLDB and .NET SOS Debugging Tool

Source: https://docs.spacestation14.com/en/server-hosting/maintenance/debugging-server-lockups

This section covers the installation of LLDB and the dotnet-sos tool, which is essential for debugging .NET core dumps. Ensure you have the correct package manager commands for your system.

```bash
sudo apt install lldb
dotnet tool install -g dotnet-sos
dotnet sos install
```

--------------------------------

### Build SS14.Admin using .NET SDK

Source: https://docs.spacestation14.com/en/server-hosting/setting-up-ss14-admin

Commands to clone the SS14.Admin repository and publish a self-contained release build using the .NET SDK. This is an alternative to using Docker, requiring Git and the .NET SDK on the build machine.

```bash
git clone https://github.com/space-wizards/SS14.Admin.git --recurse-submodules
cd SS14.Admin
dotnet publish -c Release -r linux-x64 --no-self-contained

```

--------------------------------

### Add GuideHelpComponent to Entity Prototype

Source: https://docs.spacestation14.com/en/general-development/tips/writing-guidebook-entries

This snippet demonstrates how to add the `GuideHelpComponent` to an entity prototype. This component allows players to access a specific guide by clicking a question mark in the examine window. The `guides` field accepts a list of guide IDs to be opened.

```yaml
- type: entity
  id: BaseStockPart
  name: stock part
  parent: BaseItem
  description: What?
  abstract: true
  components:
    - type: Sprite
      netsync: false
      sprite: Objects/Misc/stock_parts.rsi
    - type: Item
      size: 1
    #this is the part you add
    - type: GuideHelp 
      guides:
      - MachineUpgrading #this is the guide that is opened
```

--------------------------------

### Example Entity Sorting

Source: https://docs.spacestation14.com/en/robust-toolbox/toolshed/commands/general

An example demonstrating how to sort entities based on all components and their counts.

```C#
entities sortby { allcomps count }
```

--------------------------------

### SS14.Admin Configuration File (appsettings.yml)

Source: https://docs.spacestation14.com/en/server-hosting/setting-up-ss14-admin

An example of the appsettings.yml file used to configure SS14.Admin. It covers logging settings (Serilog), database connection strings, allowed hosts, server URLs, web root path, and trusted reverse proxy IP addresses.

```yaml
Serilog:
    Using: [ "Serilog.Sinks.Console" ]
    MinimumLevel:
        Default: Information
        Override:
            SS14: Debug
            Microsoft: "Warning"
            Microsoft.Hosting.Lifetime: "Information"
            Microsoft.AspNetCore: Warning
            IdentityServer4: Warning
    WriteTo:
        - Name: Console
          Args:
              OutputTemplate: "[{Timestamp:HH:mm:ss} {Level:u} {SourceContext}] {Message:lj}{NewLine}{Exception}"

    Enrich: [ "FromLogContext" ]

    #Loki:
    #    Address: "http://localhost:3102"
    #    Name: "centcomm"

ConnectionStrings:
    # Connect this to the same PostgreSQL database as your SS14 server
    DefaultConnection: "Server=127.0.0.1;Port=5432;Database=ss14;User Id=ss14-admin;Password=foobar"

# Set this to the domain name you will be hosting SS14.Admin under.
AllowedHosts: "ss14-admin.spacestation14.com"

# If you like to change the port of the webserver change it here, I recommend you reverse proxy this for SSL
urls: "http://localhost:27689/"

# Subpath that the site will be hosted on.
# You can leave this out if you are hosting it behind its own subdomain.
# PathBase: "/admin"

# Make sure this points to the wwwroot, it should be in the same directory as the executable
WebRootPath: "/opt/ss14_admin/bin/wwwroot"

# IP addresses that are allowed to reverse proxy the site.
# Change this if your reverse proxy isn't coming in from localhost,
# for example if SS14.Admin is running in a container,
# you should add the IP of the host in the container network here.
ForwardProxies:
    - 127.0.0.1

```

--------------------------------

### Verify Server Startup

Source: https://docs.spacestation14.com/en/general-development/setup/server-hosting-tutorial

After building the server, you can verify it is running correctly by executing the server binary in the build directory. Successful execution will print a series of messages to the console without indicating any errors.

```bash
./Robust.Server
```

--------------------------------

### Entity Component System Example (C#)

Source: https://docs.spacestation14.com/en/maintainer-meetings/maintainer-meeting-2022-03-05

Demonstrates how to use an EntityQuery to access components, replacing direct field assignments. This approach enhances efficiency and maintainability in the entity-component system.

```csharp
HashSet<EntityUid> ActiveWelders

// Instead of:
// SomeField = GetEntity(<Entity ID>).GetComponent<ActiveWelderComponent>()

// Use:
// var query = EntityQueryEnumerator<ActiveWelderComponent>();
// while (query.MoveNext(out var uid, out var component))
// {
//    // Process ActiveWelders
// }
```

--------------------------------

### Complex YAML Prototype Definition (SS14 Example)

Source: https://docs.spacestation14.com/en/general-development/tips/yaml-crash-course

A comprehensive example of a YAML prototype definition in SpaceStation 14, showcasing nested lists, dictionaries, and specific component structures. It includes comments explaining the different parts of the definition.

```yaml
# First, this entire thing is stored in a massive list. That's why there's a -.
# We're looking at one entry, a dictionary.
- type: entity # Simple key/value pairs.
  id: SMES
  name: SMES
  description: Stores power in its super-magnetic cells
  components:
  # AHA! A list in a key. Wow!
  # This list ALSO stores dictionaries.
  - type: Sprite
    sprite: Buildings/smes.rsi
    scale: 2, 2
    layers:
    - state: smes
    - state: smes-display
      shader: unshaded
    # Input lights.
    - shader: unshaded
      state: smes-oc0
    # Charge meter.
    - visible: false
      shader: unshaded
      state: smes-og1
    # Output lights.
    - shader: unshaded
      state: smes-op0
  - type: Icon
    sprite: Buildings/smes.rsi
    state: smes

```

--------------------------------

### Serve Documentation Locally with mdbook

Source: https://docs.spacestation14.com/en/meta/guide-to-editing-docs

Builds and locally hosts the documentation website. Assumes mdbook has been installed. The documentation will be available at localhost:3000.

```bash
mdbook serve
```

--------------------------------

### Emplace Command Example: Get Entity Y-Coordinates

Source: https://docs.spacestation14.com/en/robust-toolbox/toolshed/commands/emplace

The 'emplace' command iterates over entities and executes a command block. This example specifically extracts and returns the y-coordinate ('$wy') of each entity. It's useful for accessing entity properties as arguments for other commands.

```toolshed
entities emplace { var $wy }
```

--------------------------------

### Action Toolbar Setup Command

Source: https://docs.spacestation14.com/en/space-station-14/mapping/guides/general-guide

Loads a preset collection of mapping actions to the toolbar. These actions are specific to the currently controlled entity and may be lost after using ghost or possession commands.

```text
mappingclientsidesetup: load preset mapping actions to the toolbar
```

--------------------------------

### MediaWiki Integration

Source: https://docs.spacestation14.com/en/server-hosting/oauth

Configuration guide for integrating the SS14 authentication hub with a MediaWiki installation using PluggableAuth and OpenIDConnect extensions.

```APIDOC
## MediaWiki Integration

### Description
This guide explains how to integrate the SS14 authentication hub with a MediaWiki installation. It requires manual backend configuration and specific MediaWiki extensions.

### Prerequisites
- Install MediaWiki extensions: `PluggableAuth` and `OpenIDConnect`.
- Create an OAuth application on the SS14 website with the correct parameters (see 'Creating an OAuth Application').
- Ask in `#hosting` for any necessary manual back-end setup.

### Configuration (`LocalSettings.php`)

```php
<?php

// Load extensions
wfLoadExtension( 'PluggableAuth' );
wfLoadExtension( 'OpenIDConnect' );

// PluggableAuth configuration
$wgPluggableAuth_Config[] = [
        'plugin' => 'OpenIDConnect',
        'data' => [
                'providerURL' => 'https://account.spacestation14.com/',
                'clientID' => 'YOUR_CLIENT_ID', // Replace with your generated client ID.
                'clientsecret' => 'YOUR_CLIENT_SECRET', // Replace with your generated client secret.
                'scope' => [ 'profile', 'email' ]
        ]
];

// OpenIDConnect specific configuration
$wgOpenIDConnect_MigrateUsersByUserName = true;

?>
```

### Important Notes for MediaWiki
- Ensure the "Require PKCE" option is unticked during OAuth app creation.
- If experiencing issues, verify the redirect URI and consult the troubleshooting section.
```

--------------------------------

### YAML Custom Tag Example

Source: https://docs.spacestation14.com/en/general-development/tips/yaml-crash-course

Illustrates the use of custom YAML tags, such as `!type`, which are used in SpaceStation 14 to map YAML definitions to C# classes. This syntax can be confusing for standard YAML validators.

```yaml
behaviors:
- !type:HeartBehavior {}

```

--------------------------------

### Client Download URL Configuration

Source: https://docs.spacestation14.com/en/general-development/setup/server-hosting-tutorial

Specify the HTTP or HTTPS URL for downloading the entire client build as a zip archive. This is crucial for the launcher to obtain the necessary game files.

```toml
[build]
# Download locations of the entire client build in a zip, as a HTTP (or HTTPS) URL.
download_url = ""
```

--------------------------------

### Systemd Service for SS14.Admin

Source: https://docs.spacestation14.com/en/server-hosting/setting-up-ss14-admin

A systemd service definition file to automatically manage the SS14.Admin process on a Linux system. It specifies the description, service type, working directory, the executable path, and the user to run the service as.

```ini
# /etc/systemd/system/ss14-admin.service
[Unit]
Description=SS14.Admin

[Service]
Type=notify
WorkingDirectory=/opt/ss14_admin/
ExecStart=/opt/ss14_admin/bin/SS14.Admin
User=ss14_admin

[Install]
WantedBy=multi-user.target

```

--------------------------------

### Troubleshoot .NET Publish Settings for Watchdog

Source: https://docs.spacestation14.com/en/general-development/setup/server-hosting-tutorial

This section addresses the `System.IO.FileNotFoundException` for 'Mono.Posix.NETStandard, Version=1.0.0.0'. The issue is related to incorrect `dotnet publish` settings. The examples show how different publish commands affect the inclusion of `Mono.Posix.NETStandard.dll` and `System.dll`, which is crucial for marking executables on Linux and Mac OS X.

```bash
dotnet publish -c Release -r linux-x64 --no-self-contained SS14.Watchdog -o test
 RESULT: Mono.Posix.NETStandard.dll included, System.dll not included (as expected)
```

```bash
dotnet publish -c Release -r linux-x64 SS14.Watchdog -o test
 RESULT: Mono.Posix.NETStandard.dll included, System.dll included
```

```bash
dotnet publish -c Release SS14.Watchdog -o test
 RESULT: Mono.Posix.NETStandard.dll not included, System.dll not included
```

--------------------------------

### YAML Nested Structures (Dictionary of Lists)

Source: https://docs.spacestation14.com/en/general-development/tips/yaml-crash-course

Shows how to nest a list within a dictionary in YAML. The list items must start on the line following the dictionary key, indented appropriately. This allows for structured data within key-value pairs.

```yaml
A:
- "X"
- "Y"
- "Z"
B:
- "U"
- "V"
- "W"

```

--------------------------------

### Spacestation 14 BUI State Update Example (C#)

Source: https://docs.spacestation14.com/en/ss14-by-example/ui-and-you

Demonstrates how to update a Bound User Interface (BUI) when an entity's state changes. This C# example uses `TryGetOpenUi` to find an open BUI and then calls `Reload` to refresh its content based on the updated state.

```csharp
private void OnJukeboxAfterState(Entity<JukeboxComponent> ent, ref AfterAutoHandleStateEvent args)
{
    if (!_uiSystem.TryGetOpenUi<JukeboxBoundUserInterface>(ent.Owner, JukeboxUiKey.Key, out var bui))
        return;

    bui.Reload();
}
```

--------------------------------

### Define a Construction Recipe (YAML)

Source: https://docs.spacestation14.com/en/space-station-14/core-tech/construction

This YAML configuration defines a construction recipe for a 'girder'. It specifies details like the recipe ID, construction graph, starting and target nodes, category, description, icon, object type (Structure), and placement mode. It also includes example construction conditions.

```yaml
- type: construction

  name: girder
  
  id: girder
  
  graph: girder
  
  startNode: start
  
  targetNode: girder
  
  category: Structures
  
  description: A large structural assembly made out of metal.
  
  icon:
    sprite: /Textures/Constructible/Structures/Walls/solid.rsi
    state: wall_girder

  objectType: Structure
  
  placementMode: SnapgridCenter
  
  conditions:
    - !type:ExampleConstrutionConditionWithNoParameters {}
    
    - !type:LowWallInTile {}
    
    - !type:NoWindowsInTile {}
```

--------------------------------

### C# BlindOverlay Implementation

Source: https://docs.spacestation14.com/en/robust-toolbox/rendering/shaders

Demonstrates how to implement a custom overlay in C# by extending the `Overlay` class. This example shows how to request a screen texture, define the overlay's space, load shader instances from prototypes using `IPrototypeManager`, and draw shaders with specific parameters. It also includes methods for handling drawing logic and managing shader usage.

```csharp
public sealed class BlindOverlay : Overlay
{
    [Dependency] private readonly IPrototypeManager _prototypeManager = default!;

    // Set this to true to get a ScreenTexture. Otherwise, it is null.
    public override bool RequestScreenTexture => true;
    
    // This needs to be set to the appropriate overlay layer.
    public override OverlaySpace Space => OverlaySpace.WorldSpace;
    
    // Store references to the shaders.
    private readonly ShaderInstance _greyscaleShader;
    private readonly ShaderInstance _circleMaskShader;

    public BlindOverlay()
    {
        IoCManager.InjectDependencies(this);
        // Load shaders from prototypes
        _greyscaleShader = _prototypeManager.Index<ShaderPrototype>("GreyscaleFullscreen").InstanceUnique();
        _circleMaskShader = _prototypeManager.Index<ShaderPrototype>("CircleMask").InstanceUnique();
    }
    
    protected override bool BeforeDraw(in OverlayDrawArgs args)
    {
        // If this returns true, this shader will be drawn. If this
        // method is not overriden, it defaults to returning true,
        // i.e. the shader is always active for everyone all the time.
    }
    
    protected override void Draw(in OverlayDrawArgs args)
    {
        // If your shader needs inputs (the pixels currently on the screen),
        // you must check that it is not null and pass it into your shader.
        if (ScreenTexture == null)
            return;
            
        _greyscaleShader?.SetParameter("SCREEN_TEXTURE", ScreenTexture);
        
        var handle = args.WorldHandle;
        var viewport = args.WorldBounds;
        // draw the greyscale shader
        handle.UseShader(_greyscaleShader);
        handle.DrawRect(viewport, Color.White);
        // draw the circle mask shader
        handle.UseShader(_circleMaskShader);
        handle.DrawRect(viewport, Color.White);
        // stop using this shader
        handle.UseShader(null);
    }
}
```

--------------------------------

### C# Field Injection with IPostInjectInit

Source: https://docs.spacestation14.com/en/robust-toolbox/ioc

Demonstrates how to use field injection with the `[Dependency]` attribute in C# for the IoC Manager. It shows how to implement `IPostInjectInit` for post-injection initialization and includes logging. Note that direct logger initialization in `PostInject` might lead to race conditions and incomplete logging.

```csharp
public class MyDependency : IMyDependency, IPostInjectInit
{
    [Dependency]
    private readonly ILogger logger = default!;

    // Gets called when logger becomes available.
    public void PostInject()
    {
        logger.info("MyDependency being created!");
        // IMPORTANT: Don't actually do this specific thing with a logger. It gets the point across but is broken.
        // Because logger won't have been initialized properly yet, it has no output file.
        // As such, this message will go to the console, but will not be logged to any files. This is a bug.
    }

    public void Foo()
    {
        // This is fine of course, provided `Foo()` gets called after `BaseServer` had its way setting things up.
        logger.info("Hi!");
        Console.WriteLine("Hello World!");
    }
}
```

--------------------------------

### Docker Compose for SS14.Admin Deployment

Source: https://docs.spacestation14.com/en/server-hosting/setting-up-ss14-admin

This docker-compose.yml file defines a service for running SS14.Admin using the official Docker image. It specifies the image to use, container name, user, volume mounts for configuration, port mapping, and restart policy. Ensure the appsettings.yml is in the same directory.

```yaml
services:
  ss14_admin:
    image: ghcr.io/space-wizards/ss14.admin:1
    container_name: ss14_admin
    user: 1654:1654
    volumes:
      - ./appsettings.yml:/app/appsettings.yml
    ports:
      - 8080:8080
    restart: unless-stopped

```

--------------------------------

### Guidebook XML Entry with Markdown and Styling

Source: https://docs.spacestation14.com/en/general-development/tips/writing-guidebook-entries

An example of a more complex guidebook entry using markdown for titles, headings, lists, and color formatting. It also demonstrates the use of <Box> and <GuideEntityEmbed> for visual elements.

```xml
<Document>
# Magboots: The man, the myth, the legend
We know magboots are amazing, but just how amazing? The answer is quite clear: [color=#ff0000]extremely.[/color]
  
## Behold
<Box>
<GuideEntityEmbed Entity="ClothingShoesBootsMag" Caption="Perfect"/>
</Box>

## Additionally
<Box>Magboots are also cool for the following reasons:</Box>
- They come in multiple colors.
- They make me feel fuzzy and warm.
- They make sure I don't fly off into space.

You cannot beat the hustle of the magboots.
</Document>
```

--------------------------------

### UPnP Port Forwarding Success Message (Log)

Source: https://docs.spacestation14.com/en/server-hosting/port-forwarding

This is an example of a successful UPnP port forwarding message that may appear in the Space Station 14 server console. It indicates that the server has successfully communicated with the router and configured the specified TCP and UDP ports. Note that this message does not guarantee external accessibility.

```log
[INFO] net.upnp: Peer 0.0.0.0: Successfully UPnP port forwarded 1312/udp and 1312/tcp
```
Tokens:
Raw