dst-server 0.1.0__tar.gz

dst_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LST
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dst_server-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: dst-server
+Version: 0.1.0
+Summary: Start and control a Don't Starve Together server process.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: logbook>=1.9.2
+Requires-Dist: luaparser>=4.0.1,<5
+Requires-Dist: opentelemetry-api~=1.44.0
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: selectolax>=0.4.11,<0.5 ; extra == 'klei'
+Requires-Dist: urllib3-future>=2.22.901,<3 ; extra == 'klei'
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc~=1.44.0 ; extra == 'otel'
+Requires-Python: >=3.14
+Provides-Extra: klei
+Provides-Extra: otel
+Description-Content-Type: text/markdown
+
+# Don't Starve Together Dedicated Server Image
+
+[![Steam](https://img.shields.io/badge/Steam-000000?logo=steam&logoColor=white)](https://steamcommunity.com/groups/lst99)
+[![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/4N3aeNsFt8)
+
+English | [简体中文](README.zh-Hans.md)
+
+![Steam store header](https://shared.fastly.steamstatic.com/store_item_assets/steam/apps/322330/header_schinese.jpg?t=1736195686)
+
+Container image: `quay.io/wh2099/dst-server`
+
+The image runs every shard in one DST cluster and keeps the familiar console FIFO.
+It can also export validated game events through OpenTelemetry.
+
+## Quick Start
+
+1. Install a container runtime such as [Podman](https://docs.podman.io/en/latest/index.html).
+2. Create and download a dedicated-server configuration from [Klei's server management page](https://accounts.klei.com/account/game/servers?game=DontStarveTogether).
+3. Extract the archive on the host.
+
+   The directory mounted at `/cluster` must directly contain `cluster.ini`, `cluster_token.txt`, and the shard directories:
+
+   ```text
+   Cluster_1/
+   ├── cluster.ini
+   ├── cluster_token.txt
+   ├── Master/
+   │   └── server.ini
+   └── Caves/
+       └── server.ini
+   ```
+
+4. Start the container, replacing the host path with the extracted cluster directory:
+
+   ```shell
+   sudo podman run \
+     --name dst \
+     --detach \
+     --network host \
+     --volume "${HOME}/Cluster_1:/cluster" \
+     quay.io/wh2099/dst-server:latest
+   ```
+
+## Operations
+
+```shell
+podman logs dst
+podman stop dst
+podman start dst
+podman restart dst
+```
+
+Stopping the container terminates every shard gracefully, and DST saves during shutdown.
+
+The entrypoint creates a named `console` pipe for the master shard at the cluster root.
+Each secondary shard receives one in its own directory:
+
+```shell
+echo 'c_announce("Server maintenance is coming.")' > "${HOME}/Cluster_1/console"
+echo 'c_save()' > "${HOME}/Cluster_1/Caves/console"
+```
+
+Common lifecycle commands include `c_reset()`, `c_regenerateworld()`, `c_save()`, and `c_shutdown(false)`.
+Use `c_announce("...")` to send a message and `c_listallplayers()` to inspect players.
+
+## What the Entrypoint Does
+
+On startup, [`entrypoint.py`](entrypoint.py) validates the cluster and prepares permission and Mod files.
+It updates Workshop content once, discovers every shard, and starts one `Server` per shard in `-cloudserver` mode.
+
+`DST_SKIP_MOD_UPDATE=1` skips the one-shot Workshop update.
+
+`DST_INSTALL_PATH` and `DST_CLUSTER_PATH` override `/install` and `/cluster` for development and tests.
+
+An `OTEL_EXPORTER_OTLP_*_ENDPOINT` variable enables the official OpenTelemetry pipeline.
+The entrypoint then exports validated game events.
+
+## Python SDK
+
+The `dst-server` package starts and controls one Linux DST shard process.
+
+```python
+import asyncio
+
+from dst_server import Server, ServerArgs
+
+
+async def main() -> None:
+    async with Server(ServerArgs(shard="Master")) as server:
+        world = await server.game.world.state()
+        players = await server.game.players.list()
+        await server.game.world.announce(
+            f"Day {world.day}: {len(players)} player(s) online"
+        )
+        await server.save()
+
+
+asyncio.run(main())
+```
+
+The typed API covers world and player queries, inventory, administration, confirmed saves, and raw Lua.
+It also exposes lifecycle and game events.
+
+Install `dst-server[otel]` for OTLP export or `dst-server[klei]` for Klei build and lobby services.
+
+## Lua Annotations
+
+The `dst-annotations` command generates LSP-compatible Lua definitions from DST components or `modutil.lua`.
+
+```console
+dst-annotations dst-scripts/scripts/components --output components_def.lua
+dst-annotations dst-scripts/scripts/modutil.lua --output modutil_def.lua
+```
+
+## Documentation
+
+Game server reference:
+
+- [Cluster architecture and configuration files](docs/dedicated-server-configuration.md)
+- [Dedicated server command-line options](docs/dedicated-server-options.md)
+
+Technical design:
+
+- [`-cloudserver` bidirectional IPC](docs/cloudserver-ipc.md)
+- [Game events and OpenTelemetry](docs/opentelemetry-game-events.md)
+
+Source reference:
+
+- [DST Lua source index](dst-scripts/index/README.md)
+
+The detailed documentation is maintained in Simplified Chinese.

dst_server-0.1.0/README.md

@@ -0,0 +1,131 @@
+# Don't Starve Together Dedicated Server Image
+
+[![Steam](https://img.shields.io/badge/Steam-000000?logo=steam&logoColor=white)](https://steamcommunity.com/groups/lst99)
+[![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/4N3aeNsFt8)
+
+English | [简体中文](README.zh-Hans.md)
+
+![Steam store header](https://shared.fastly.steamstatic.com/store_item_assets/steam/apps/322330/header_schinese.jpg?t=1736195686)
+
+Container image: `quay.io/wh2099/dst-server`
+
+The image runs every shard in one DST cluster and keeps the familiar console FIFO.
+It can also export validated game events through OpenTelemetry.
+
+## Quick Start
+
+1. Install a container runtime such as [Podman](https://docs.podman.io/en/latest/index.html).
+2. Create and download a dedicated-server configuration from [Klei's server management page](https://accounts.klei.com/account/game/servers?game=DontStarveTogether).
+3. Extract the archive on the host.
+
+   The directory mounted at `/cluster` must directly contain `cluster.ini`, `cluster_token.txt`, and the shard directories:
+
+   ```text
+   Cluster_1/
+   ├── cluster.ini
+   ├── cluster_token.txt
+   ├── Master/
+   │   └── server.ini
+   └── Caves/
+       └── server.ini
+   ```
+
+4. Start the container, replacing the host path with the extracted cluster directory:
+
+   ```shell
+   sudo podman run \
+     --name dst \
+     --detach \
+     --network host \
+     --volume "${HOME}/Cluster_1:/cluster" \
+     quay.io/wh2099/dst-server:latest
+   ```
+
+## Operations
+
+```shell
+podman logs dst
+podman stop dst
+podman start dst
+podman restart dst
+```
+
+Stopping the container terminates every shard gracefully, and DST saves during shutdown.
+
+The entrypoint creates a named `console` pipe for the master shard at the cluster root.
+Each secondary shard receives one in its own directory:
+
+```shell
+echo 'c_announce("Server maintenance is coming.")' > "${HOME}/Cluster_1/console"
+echo 'c_save()' > "${HOME}/Cluster_1/Caves/console"
+```
+
+Common lifecycle commands include `c_reset()`, `c_regenerateworld()`, `c_save()`, and `c_shutdown(false)`.
+Use `c_announce("...")` to send a message and `c_listallplayers()` to inspect players.
+
+## What the Entrypoint Does
+
+On startup, [`entrypoint.py`](entrypoint.py) validates the cluster and prepares permission and Mod files.
+It updates Workshop content once, discovers every shard, and starts one `Server` per shard in `-cloudserver` mode.
+
+`DST_SKIP_MOD_UPDATE=1` skips the one-shot Workshop update.
+
+`DST_INSTALL_PATH` and `DST_CLUSTER_PATH` override `/install` and `/cluster` for development and tests.
+
+An `OTEL_EXPORTER_OTLP_*_ENDPOINT` variable enables the official OpenTelemetry pipeline.
+The entrypoint then exports validated game events.
+
+## Python SDK
+
+The `dst-server` package starts and controls one Linux DST shard process.
+
+```python
+import asyncio
+
+from dst_server import Server, ServerArgs
+
+
+async def main() -> None:
+    async with Server(ServerArgs(shard="Master")) as server:
+        world = await server.game.world.state()
+        players = await server.game.players.list()
+        await server.game.world.announce(
+            f"Day {world.day}: {len(players)} player(s) online"
+        )
+        await server.save()
+
+
+asyncio.run(main())
+```
+
+The typed API covers world and player queries, inventory, administration, confirmed saves, and raw Lua.
+It also exposes lifecycle and game events.
+
+Install `dst-server[otel]` for OTLP export or `dst-server[klei]` for Klei build and lobby services.
+
+## Lua Annotations
+
+The `dst-annotations` command generates LSP-compatible Lua definitions from DST components or `modutil.lua`.
+
+```console
+dst-annotations dst-scripts/scripts/components --output components_def.lua
+dst-annotations dst-scripts/scripts/modutil.lua --output modutil_def.lua
+```
+
+## Documentation
+
+Game server reference:
+
+- [Cluster architecture and configuration files](docs/dedicated-server-configuration.md)
+- [Dedicated server command-line options](docs/dedicated-server-options.md)
+
+Technical design:
+
+- [`-cloudserver` bidirectional IPC](docs/cloudserver-ipc.md)
+- [Game events and OpenTelemetry](docs/opentelemetry-game-events.md)
+
+Source reference:
+
+- [DST Lua source index](dst-scripts/index/README.md)
+
+The detailed documentation is maintained in Simplified Chinese.

dst_server-0.1.0/pyproject.toml

@@ -0,0 +1,86 @@
+[project]
+name = "dst-server"
+version = "0.1.0"
+description = "Start and control a Don't Starve Together server process."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+dependencies = [
+    "logbook>=1.9.2",
+    "luaparser>=4.0.1,<5",
+    "opentelemetry-api~=1.44.0",
+    "pydantic>=2.13.4",
+]
+
+[project.optional-dependencies]
+klei = ["selectolax>=0.4.11,<0.5", "urllib3-future>=2.22.901,<3"]
+otel = ["opentelemetry-exporter-otlp-proto-grpc~=1.44.0"]
+
+[project.scripts]
+dst-annotations = "dst_server.annotations.cli:main"
+
+[dependency-groups]
+dev = [
+    "prek>=0.4.10",
+    "pytest>=9.1.0",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.15.17",
+    "rumdl>=0.2.35",
+    "ty>=0.0.49",
+]
+
+[build-system]
+requires = ["uv_build~=0.11"]
+build-backend = "uv_build"
+
+[tool.ruff]
+fix = true
+preview = true
+required-version = '>=0.15'
+
+[tool.ruff.lint]
+select = ['ALL']
+ignore = [
+    'missing-trailing-comma',        # Conflicts with `ruff format`.
+    'commented-out-code',            # False positives are common.
+    'TC',                            # Runtime use of typing constructs is common now.
+    'CPY',                           # Covered by the standalone LICENSE file.
+    'too-many-arguments',            # Explicit is better than implicit.
+    'too-many-positional-arguments', # Complex is better than complicated.
+    'no-self-use',                   # Violates the usual practice.
+    'any-type',                      # Framework boundaries carry protocol and DI values.
+    'builtin-argument-shadowing',    # Event(type=...) is part of the public API.
+    'blind-except',                  # Dispatch records handler exceptions before re-raising.
+    'D',                             # Too verbose.
+    'subclass-builtin',              # Message and State intentionally mirror built-in containers.
+    'FBT',                           # Too strict.
+    'import-outside-top-level',      # Optional runtime imports keep hard dependencies lazy.
+    'too-many-return-statements',    # Small resolver functions are branchy by nature.
+]
+
+[tool.ruff.lint.pydoclint]
+ignore-one-line-docstrings = true
+
+[tool.ruff.lint.per-file-ignores]
+'src/dst_server/annotations/visitors.py' = ['invalid-function-name']
+'tests/**/*.py' = [
+    'assert',                     # Assert statements used for pytest.
+    'implicit-namespace-package', # Colocated tests are plain directories, not import packages.
+    'magic-value-comparison',     # Magic value used in test cases.
+    'import-private-name',        # OpenTelemetry still exposes private log modules.
+    'compare-to-empty-string',    # Explicit empty-string comparisons aid assertions.
+    'private-member-access',      # Tests may cover implementation details.
+]
+
+[tool.ty.environment]
+python-platform = "linux"
+
+[tool.pytest]
+minversion = '9.0'
+asyncio_mode = 'auto'
+
+[tool.rumdl]
+enable = ['ALL']
+line-length = 120
+exclude = ['.git', '.github', 'LICENSE']

dst_server-0.1.0/src/dst_server/__init__.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from .arguments import ServerArgs
+from .cluster import Shard, ShardConfig, discover_shards, ensure_fifo, prepare_cluster
+from .events import (
+    DriverHealth,
+    EntityRef,
+    GameEvent,
+    ItemRef,
+    ObservedGameEvent,
+    ServerEvent,
+    ServerReadyEvent,
+    ServerSavedEvent,
+    ServerSessionEvent,
+    ServerShutdownEvent,
+    ServerStoppingEvent,
+    TelemetrySettings,
+    UnknownServerEvent,
+)
+from .game import GameClient
+from .models import (
+    Age,
+    Container,
+    Entity,
+    EquipmentSlot,
+    Health,
+    Inventory,
+    InventorySlot,
+    Item,
+    Mod,
+    Player,
+    PlayerState,
+    Position,
+    Room,
+    Runtime,
+    ShardStatus,
+    Stat,
+    Temperature,
+    Vitals,
+    World,
+)
+from .mods import prepare_mods, update_server_mods, workshop_mod_ids
+from .process import Server
+
+__all__ = [
+    "Age",
+    "Container",
+    "DriverHealth",
+    "Entity",
+    "EntityRef",
+    "EquipmentSlot",
+    "GameClient",
+    "GameEvent",
+    "Health",
+    "Inventory",
+    "InventorySlot",
+    "Item",
+    "ItemRef",
+    "Mod",
+    "ObservedGameEvent",
+    "Player",
+    "PlayerState",
+    "Position",
+    "Room",
+    "Runtime",
+    "Server",
+    "ServerArgs",
+    "ServerEvent",
+    "ServerReadyEvent",
+    "ServerSavedEvent",
+    "ServerSessionEvent",
+    "ServerShutdownEvent",
+    "ServerStoppingEvent",
+    "Shard",
+    "ShardConfig",
+    "ShardStatus",
+    "Stat",
+    "TelemetrySettings",
+    "Temperature",
+    "UnknownServerEvent",
+    "Vitals",
+    "World",
+    "discover_shards",
+    "ensure_fifo",
+    "prepare_cluster",
+    "prepare_mods",
+    "update_server_mods",
+    "workshop_mod_ids",
+]

dst_server-0.1.0/src/dst_server/_fd_wrapper.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+import os
+import sys
+
+_PROTOCOL_FDS = (3, 4, 5)
+
+
+def main() -> None:
+    sources = tuple(int(value) for value in sys.argv[1:4])
+    command = sys.argv[4:]
+    if len(sources) != len(_PROTOCOL_FDS) or not command:
+        msg = "usage: _fd_wrapper.py FD3 FD4 FD5 COMMAND [ARG ...]"
+        raise SystemExit(msg)
+    for source, target in zip(sources, _PROTOCOL_FDS, strict=True):
+        os.dup2(source, target, inheritable=True)
+    for source in sources:
+        if source not in _PROTOCOL_FDS:
+            os.close(source)
+    os.execv(command[0], command)  # ruff:ignore[start-process-with-no-shell]
+
+
+if __name__ == "__main__":
+    main()

dst_server-0.1.0/src/dst_server/annotations/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .generator import generate_components, generate_modutil
+
+__all__ = ["generate_components", "generate_modutil"]

dst_server-0.1.0/src/dst_server/annotations/cli.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import argparse
+import logging
+from collections.abc import Sequence
+from pathlib import Path
+
+from .generator import generate_components, generate_modutil
+
+logger = logging.getLogger(__name__)
+
+
+def create_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Generate LSP-compatible Lua annotations."
+    )
+    parser.add_argument("input", type=Path, help="Components directory or modutil file")
+    parser.add_argument("-o", "--output", type=Path, help="Output Lua file")
+    parser.add_argument("-m", "--max-workers", type=int, help="Worker process count")
+    parser.add_argument(
+        "--mode",
+        choices=("auto", "components", "modutil"),
+        default="auto",
+    )
+    return parser
+
+
+def resolve_mode(
+    parser: argparse.ArgumentParser,
+    input_path: Path,
+    requested: str,
+) -> str:
+    if requested != "auto":
+        return requested
+    if input_path.is_dir():
+        return "components"
+    if input_path.is_file() and "modutil" in input_path.name.lower():
+        return "modutil"
+    return parser.error("Cannot infer mode; pass --mode explicitly.")
+
+
+def write_components(input_path: Path, output: Path | None, workers: int | None) -> int:
+    content = generate_components(input_path, workers)
+    if not content:
+        logger.error("No Lua component definitions generated from %s", input_path)
+        return 1
+
+    output_path = output or Path(f"{input_path.name}_def.lua")
+    output_path.write_text(content, encoding="utf-8")
+    logger.info("Output written to %s", output_path)
+    return 0
+
+
+def write_modutil(input_path: Path, output: Path | None) -> int:
+    if not input_path.is_file():
+        raise FileNotFoundError(input_path)
+
+    content = generate_modutil(input_path)
+    if not content:
+        logger.error("No definitions found in %s", input_path)
+        return 1
+
+    output_path = output or Path(f"{input_path.stem}_def.lua")
+    output_path.write_text(content, encoding="utf-8")
+    logger.info("Output written to %s", output_path)
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    parser = create_parser()
+    args = parser.parse_args(argv)
+    mode = resolve_mode(parser, args.input, args.mode)
+
+    try:
+        if mode == "components":
+            return write_components(args.input, args.output, args.max_workers)
+        return write_modutil(args.input, args.output)
+    except Exception as error:
+        parser.error(str(error))

dst_server-0.1.0/src/dst_server/annotations/generator.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import logging
+from concurrent.futures import ProcessPoolExecutor
+from itertools import repeat
+from pathlib import Path
+
+from .visitors import DEFAULT_VAR, parse_component, parse_modutil
+
+logger = logging.getLogger(__name__)
+
+
+def extract_class_name(content: str) -> str | None:
+    for source_line in reversed(content.splitlines()):
+        line = source_line.strip()
+        if line.startswith("return "):
+            return line.removeprefix("return ").split(maxsplit=1)[0].rstrip(",")
+    return None
+
+
+def component_definition(path: Path, folder_name: str) -> tuple[str, str] | None:
+    try:
+        content = path.read_text(encoding="utf-8")
+        class_name = extract_class_name(content) or path.stem
+        fields, definitions = parse_component(
+            content,
+            path.stem,
+            class_name,
+            folder_name,
+        )
+    except Exception as error:
+        logger.warning("Could not parse %s: %s", path, error)
+        return None
+
+    lines = [f"---@class {class_name}", *fields]
+    lines.extend((
+        f"local {DEFAULT_VAR}={{}}",
+        f"{folder_name}.{path.stem}={DEFAULT_VAR}",
+        "",
+        *definitions,
+        "",
+    ))
+    return path.stem, "\n".join(lines)
+
+
+def generate_components(input_dir: Path, max_workers: int | None = None) -> str:
+    if not input_dir.is_dir():
+        raise NotADirectoryError(input_dir)
+
+    files = sorted(input_dir.rglob("*.lua"))
+    if max_workers == 1:
+        results = [component_definition(path, input_dir.name) for path in files]
+    else:
+        with ProcessPoolExecutor(max_workers=max_workers) as executor:
+            results = list(
+                executor.map(component_definition, files, repeat(input_dir.name))
+            )
+
+    definitions = sorted(result for result in results if result is not None)
+    return "\n".join(content for _, content in definitions)
+
+
+def generate_modutil(input_file: Path) -> str:
+    content = input_file.read_text(encoding="utf-8")
+    definitions = parse_modutil(content, input_file.stem)
+    return "\n".join(definitions) + ("\n" if definitions else "")