### 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 ActiveWelders // Instead of: // SomeField = GetEntity().GetComponent() // Use: // var query = EntityQueryEnumerator(); // 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 '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 ent, ref AfterAutoHandleStateEvent args) { if (!_uiSystem.TryGetOpenUi(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("GreyscaleFullscreen").InstanceUnique(); _circleMaskShader = _prototypeManager.Index("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 and for visual elements. ```xml # 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 ## Additionally Magboots are also cool for the following reasons: - 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. ``` -------------------------------- ### 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 ```