Unify the SLS and SLS-LITE blueprint schema

[Yeetoxic]

Goal

Define one portable blueprint schema shared by full SLS and SLS-LITE.

A blueprint should describe the server being assembled without depending on whether it runs through distributed SLS infrastructure or the local Minecraft-focused SLS-LITE runtime.

The implementations may differ, but a shared field should always express the same intent.

SLS-LITE is still in its release-candidate period, so its experimental blueprint fields may be changed or removed to reach a cleaner shared design. Breaking changes are acceptable if testers receive clear migration instructions and actionable validation errors.

Add individual file state

The shared schema currently provides:

• state.volumes for directories
• state.copy for assembly inputs
• save for retaining an instance

Neither state.copy nor a complete writable directory cleanly represents an individual file with an ongoing persistence relationship.

Proposed shared form:

state:
  files:
    - name: access-list
      source: access/lobby.json
      target: config/access.json
      mode: persistent

Possible modes:

• private: each instance receives an independent writable copy; changes never affect the source.
• persistent: one instance owns the file while active and publishes its changes back after stopping.

Example use cases

A private file could provide a default configuration that every new instance may customize independently:

state:
  files:
    - name: default-settings
      source: templates/settings.json
      target: config/settings.json
      mode: private

A persistent file could retain an access list, player registry, save index, or application-generated configuration without granting the instance write access to an entire directory:

state:
  files:
    - name: whitelist
      source: whitelists/survival.json
      target: whitelist.json
      mode: persistent

state.copy would remain the general one-way assembly operation. state.files would describe a continuing relationship between a source file and an instance file.

SLS-LITE’s experimental state.persistent_files field can be replaced by this shared form.

Define writable-volume ownership

An rw volume exposes a writable directory directly to an instance, but the blueprint does not currently state whether another instance may use it simultaneously.

Proposed shared form:

state:
  volumes:
    - name: persistent-data
      source: game-data/survival
      target: /data
      mode: rw
      access: exclusive

Possible policies:

• exclusive: only one active instance may use the writable source.
• shared: concurrent access is intentional and coordinated by the application.

Example use cases

A game world or embedded database generally requires exclusive ownership:

state:
  volumes:
    - name: world
      source: worlds/survival
      target: /world
      mode: rw
      access: exclusive

A directory containing assets designed for concurrent updates may deliberately allow shared access:

state:
  volumes:
    - name: shared-assets
      source: assets/network
      target: /assets
      mode: rw
      access: shared

This lets operators express their intent instead of relying on instance-count conventions.

Full SLS would coordinate exclusive ownership across Protocube and its nodes. SLS-LITE would enforce the same contract locally.

Unify instance limits

SLS-LITE currently adds:

server:
  limits:
    max_players: 20
    max_instances: 2

These concepts can also be useful to full SLS:

• max_players defines the public capacity of an instance.
• max_instances limits how many instances may be created from a blueprint.

Example use cases

A small match server might permit eight players and scale to four simultaneous matches:

server:
  limits:
    max_players: 8
    max_instances: 4

A persistent survival server might allow many players but only one instance:

server:
  limits:
    max_players: 50
    max_instances: 1

We should decide whether these remain under server.limits or move into a dedicated capacity or scheduling section. SLS-LITE can migrate to whichever structure becomes canonical.

Define a shared blueprint-ID format

SLS-LITE currently restricts IDs to portable lowercase slugs because IDs are used in paths, commands, APIs, process identities, and proxy registrations.

For example:

blueprint:
  id: survival_events

A shared format avoids one implementation accepting an ID that becomes ambiguous or unsafe in another environment.

Both projects should publish one grammar and normalization policy.

Use a shared logical storage root

Full SLS and SLS-LITE currently interpret source paths from different physical roots.

The blueprint should use a logical managed-storage path:

state:
  volumes:
    - name: lobby
      source: worlds/lobby
      target: /world
      mode: cow

Full SLS may resolve this below its configured volume storage, while SLS-LITE resolves it below its plugin-owned volumes directory.

Why this matters

A blueprint containing:

source: worlds/lobby

should not need to become:

source: volumes/worlds/lobby

when moved between products. The physical storage layout belongs to the implementation, not the blueprint.

SLS-LITE can remove the extra volumes/ prefix from its canonical schema and provide migration guidance for existing RC blueprints.

Migration approach

Because SLS-LITE is still pre-release, we should prioritize a clean shared schema over preserving every experimental LITE field.

Possible SLS-LITE changes include:

• Replace state.persistent_files with state.files.
• Change volume and file sources to use the shared logical storage root.
• Move max_players or max_instances if a better shared section is selected.
• Adopt the shared ID rules.
• Reject old declarations with an error showing the corrected form.

For example:

Blueprint uses the removed field 'state.persistent_files'.
Replace it with 'state.files' and add 'mode: persistent'.
See: <migration documentation>

Full SLS may require a more conservative compatibility or schema-versioning plan because its blueprint format is already established.

Compatibility principles

• Both projects document one canonical schema.
• A shared field has the same meaning in both implementations.
• Physical paths, containers, processes, and node topology remain runtime details.
• Game-specific fields are optional and do not prevent other games from using the schema.
• SLS-LITE may break experimental RC syntax to reach the shared contract.
• Every breaking change includes a migration example and actionable error.
• Existing full-SLS blueprints receive an appropriate compatibility path.
• Runtime-specific capabilities fail clearly rather than silently changing meaning.

Proposed work

• Agree on state.files and its modes.
• Define exclusive and shared writable-state behavior.
• Design cross-node ownership for full SLS.
• Implement equivalent local ownership in SLS-LITE.
• Choose canonical capacity and instance-limit fields.
• Define a shared blueprint-ID format.
• Define sources relative to a common logical storage root.
• Decide whether full SLS requires a schema version.
• Write SLS-LITE migration guidance for changed RC fields.
• Publish shared examples covering each feature and use case.
• Run the same blueprint compatibility fixtures in both projects.

[jessefaler]

Add individual file state

Private files

I don't see a big use for this. This can already be achieved with a COW mount or state.copy, both of which give you your own private file/folder.

Persistent files

I looked over how you implemented persistent files in SLS-LITE, and from what I can see, only one instance can use the persistent file at a time. If you try to start another instance while the persistent file is in use, it will fail, so you can only ever have one instance running with it. In that case, you might as well use an RW bind mount with max-instances set to 1. Bind mounts also do support mounting individual files, SLS right now dose not allow it but I could add in support for it.

Concurrency should also generally be handled by the application accessing the data. If an application is designed to support multiple instances reading/writing the same files, it should provide its own synchronization, such as file locking or database level locking. SQLite for example, has its own locking mechanisms for safely coordinating concurrent access.

Define writable-volume ownership

This is something I think should be enforced on the source directory itself rather than in each individual blueprint that mounts it.

Each blueprint could otherwise define its own access rule for the same volume, which could conflict with what other blueprints have set. For example, one blueprint could mount a volume with access: exclusive while another mounts it with access: shared.

The best way to do this would be to have separate volume configuration files where you define a source path and its access rules. Any blueprint that uses that source path would automatically be subject to those rules.

# storage-registry.yaml
volumes:
  - name: survival
    source: worlds/survival
    access: exclusive # The source itself dictates its access policy

Any blueprint that mounts worlds/survival would be subject to its access policy.

That being said, I probably won't implement this in SLS any time soon. There are a lot of other features I want to focus on first. In the meantime, max-instances: 1 can pretty much accomplish this.

shared is also more of an advisory setting. While it would be nice to know that a volume will be accessed by multiple instances, I don't think it's worth adding. It's typically implied when mounting read/write volumes that multiple instances may share access.

Unify instance limits

maxPlayers and max-instances already exist in vSLS and can be set via an annotation.

See: https://protoxon.github.io/sls-docs/guide/vsls/configuring.html

annotations:
  vsls:
    # At most one concurrent instance of this blueprint.
    max-instances: 1

    matchmaking:
      # Controls the number of players per instance.
      # Omit to allow unlimited players.
      maxPlayers: 1

maxPlayers will remain an annotation for vSLS because player count can and should be managed by the proxy. The SLS backend shouldn't try to enforce player limits.

max-instances is something I would like to add directly into SLS's backend rather than having it in vSLS, so it can be enforced by Protocube. I would likely place it under the main server block rather than under limits, like this:

server:
  software: "paper"
  version: "1.21.1"
  max-instances: 1
  limits:
    memory_limit: 4096

The reason is that resource limits define the resources a single container can have, while max-instances defines how many instances of the server can exist. They're fundamentally different types of limits, so I think it makes more sense for max-instances to be part of the server configuration itself.

Restricted IDs

I like this one. I'll probably add validation that disallows most problematic special characters and spaces in IDs since those could definitely cause issues.

I don't want to enforce a specific style, though. IDs are snake_case by convention, but if someone wants to use camelCase or something else, they can. The same applies to mixin IDs.

Use a shared logical storage root

SLS lets you define any directory path for your volumes, and it appends that to the mount path:

system:
  volumes: "/var/lib/sls/volumes"

I would do the same for SLS-LITE if you want to still allow people to place volumes anywhere.

Add a configuration option that lets you define the base path. By default, it could be something like:

./plugins/sls-lite/volumes/

If someone wants the volumes directly under the SLS-LITE plugin folder, they could change it to:

./plugins/sls-lite

SLS-LITE would then append the logical source path when mounting the volume.