# ARK: Survival Ascended — dedicated server module.
#
# ASA has no native Linux server binary — it runs the Windows build under
# Proton. Rather than bundle our own 500 MB+ Wine/Proton image, this module
# uses `acekorneya/asa_server:latest`, the most actively-maintained
# community image for ASA on Linux. It packages:
#
#   - Proton + Wine runtime
#   - SteamCMD (handles install + auto-update on start)
#   - An entrypoint that reads env vars and assembles the ASA command line
#   - BattlEye / RCON / cluster flags
#
# So: the SteamCMD-style "download game via our sidecar" pattern we use for
# 7DTD doesn't apply here — the image downloads ASA itself on first boot
# via its internal SteamCMD. No external update provider needed, which is
# why this module has NO `update_providers:` section (the `Update` button
# won't do anything useful for ASA; just restart the server to pull game
# patches — the image auto-updates when UPDATE_SERVER=true is set).
#
# Operators who want to own the stack can publish their own image (Proton
# + SteamCMD + ASA) and swap `image:` below. Keep the env vars the same —
# the community entrypoint reads `SESSION_NAME`, `SERVER_ADMIN_PASSWORD`,
# `SERVER_MAP` etc.
#
# First-run flow:
#   1. Create the server in the panel → empty container + volume.
#   2. Click Start → the image's entrypoint runs SteamCMD inside the
#      container and downloads ~18 GB of ASA into /home/pok/arkserver.
#      First boot takes 15–30 minutes depending on bandwidth.
#   3. After the install finishes the server actually starts. Open Console
#      and wait for "Server started on port 7777".
#
# Subsequent starts are quick (<= 2 min) since the files are cached on the
# named volume.

id: ark-sa
name: "ARK: Survival Ascended"
version: 0.3.0
authors:
  - panel contributors

supported_modes:
  - docker

# The acekorneya image handles its own SteamCMD download on first Start
# (UPDATE_SERVER=TRUE env). Opt out of the panel's auto-update-on-create
# sidecar — its install path doesn't match the image's layout and would
# just waste ~20 minutes creating files the server won't use.
auto_update_on_create: false
# But DO auto-start after create — the image's entrypoint runs its own
# SteamCMD on first boot and then launches the server, so Create → Start
# is the one-gesture flow operators expect. (True is the default across
# all modules; declared here so the interaction with auto_update_on_create
# being false is explicit to anyone reading this file.)
auto_start_on_create: true

runtime:
  docker:
    image: acekorneya/asa_server:latest
    # Host networking -- container shares the host net namespace, so
    # any port the game/mod binds is directly on the LAN. AMP-like
    # model. Multi-instance safety comes from env-driven per-instance
    # ports (panel allocator + env: mapping on each ports entry).
    network_mode: host
    env:
      TZ: "Etc/UTC"
      # acekorneya's entrypoint expects these. They're defaults — operators
      # override per-instance once the config-values layer is wired.
      INSTANCE_NAME: "panel-asa"
      SERVER_MAP: "TheIsland_WP"
      SESSION_NAME: "Panel ARK SA Server"
      SERVER_ADMIN_PASSWORD: "changeme-please"
      SERVER_PASSWORD: ""
      ASA_PORT: "7777"
      # Steam query port. The agent rewrites this to the actually-allocated
      # host port at create time (see resolve.go's port-env mapping) — for
      # the first ARK on an agent this stays 27015; the second gets 27016
      # or whatever the allocator picked. The acekorneya image translates
      # this into the launch arg `?QueryPort=<n>` on its end.
      QUERY_PORT: "27015"
      RCON_PORT: "27020"
      MAX_PLAYERS: "70"
      # Pull any ASA patches from Steam on every start. Cheap when up to
      # date (SteamCMD validate is a few seconds) and means the server is
      # always current.
      UPDATE_SERVER: "TRUE"
      CHECK_FOR_UPDATE_INTERVAL: "24"
      UPDATE_WINDOW_MINIMUM_TIME: "12:00 AM"
      UPDATE_WINDOW_MAXIMUM_TIME: "11:59 PM"
      RESTART_NOTICE_MINUTES: "30"
      ENABLE_MOTD: "FALSE"
      MOTD: "Welcome!"
      MOTD_DURATION: "30"
      MAP_NAME: "TheIsland"
      NOTIFY_ADMIN_COMMANDS_IN_CHAT: "FALSE"
      RANDOM_STARTUP_DELAY: "FALSE"
      # BattlEye under Wine/Proton on Linux containers silently crashes the
      # server ~2-3 minutes after "Server has successfully started!" (no
      # log output between the success line and the process exit — classic
      # UE5 silent death on BE handshake failure). Operators can enable it
      # per-instance once BE for ASA/Linux gets sorted upstream; for now
      # the default is off so servers actually stay up.
      BATTLEEYE: "FALSE"
      RCON_ENABLED: "TRUE"
      DISPLAY_POK_MONITOR_MESSAGE: "FALSE"
      MOD_IDS: ""
      PASSIVE_MODS: ""
      CUSTOM_SERVER_ARGS: ""
      CLUSTER_ID: ""
      # ----- EOS / session-browser stability knobs (see post_start) -----
      # ASA reports the host's auto-detected adapter IP to Epic Online
      # Services when it registers the server session for the in-game
      # browser. Under Docker (host-networking, multiple bridges, IPv6
      # scopes) EOS sometimes picks the wrong adapter on a re-registration
      # and advertises an unreachable IP. The server stays up + RCON works
      # + connect-by-IP works, but it vanishes from the browser. ASA
      # exposes `-PublicIPForEpic=<ipv4>` to override the auto-detect.
      # Leave empty to keep ASA's default behavior; set to the WAN IPv4
      # players reach (the WG-edge VPS for this fleet) to pin EOS to it.
      # Reference: forums.unrealengine.com EOS-DS browser-visibility thread.
      PUBLIC_IP_FOR_EPIC: ""
      # Run as UID/GID 1000 so writes land on the volume as a normal user.
      PUID: "1000"
      PGID: "1000"
    # The acekorneya image runs ARK under Wine — the live install lives at
    # the Wine-virtualized Windows path below. Early module versions mounted
    # /home/pok/arkserver thinking it was a symlink; it isn't — that dir
    # doesn't exist at image build time, so the volume was essentially
    # unused, and saves/configs lived only in the container's ephemeral
    # overlay FS. Fixed by mounting DIRECTLY at the Wine path, matching
    # acekorneya's own docker-compose example. Saves, configs, logs, and
    # admin lists all live under this Saved/ dir.
    browseable_root: "/usr/games/.wine/drive_c/POK/Steam/steamapps/common/ARK Survival Ascended Dedicated Server/ShooterGame/Saved"
    volumes:
      # Whole ASA install (game binaries + ShooterGame/Saved/{configs,
      # world data, logs}). One volume keeps things simple and mirrors
      # the upstream docker-compose pattern.
      - { type: volume, name: "panel-$INSTANCE_ID-server",
          container: "/usr/games/.wine/drive_c/POK/Steam/steamapps/common/ARK Survival Ascended Dedicated Server" }
      # Cluster transfer dir — may be overridden at instance create time
      # to point at a shared `panel-ark-cluster-<id>` volume for
      # multi-server clustering (see the Cluster button in the ARK modal).
      - { type: volume, name: "panel-$INSTANCE_ID-cluster",
          container: "/usr/games/.wine/drive_c/POK/Steam/steamapps/common/ARK Survival Ascended Dedicated Server/ShooterGame/Saved/clusters" }

ports:
  # `env:` tells the agent which container env var to set with the
  # allocated host port. The acekorneya entrypoint reads ASA_PORT /
  # QUERY_PORT / RCON_PORT and assembles ARK's launch args from them
  # (?Port=N ?QueryPort=N ?RCONPort=N). Without env-mirror, the second
  # ARK instance on the same agent gets distinct host bindings but
  # ARK still advertises 7777/27015 to Steam, so the browser shows
  # only one of them.
  - { name: game,  proto: udp, default: 7777,  required: true, env: ASA_PORT }
  - { name: raw,   proto: udp, default: 7778,  required: true }
  # Steam server-browser query port. ASA registers itself with the Steam
  # master at this port, and `?QueryPort=<n>` on the ASA launch command
  # tells the engine which port to bind + advertise. Without this entry
  # in the manifest, the allocator can't pick distinct host ports for
  # multiple instances on the same agent — they all clobber 27015 and
  # only one shows up in the Steam server list.
  - { name: query, proto: udp, default: 27015, required: true, env: QUERY_PORT }
  - { name: rcon,  proto: tcp, default: 27020, internal: true, env: RCON_PORT }

# post_start: shell commands executed inside the container by the agent
# after a successful Start. Best-effort — failures log a warning but don't
# fail the Start.
#
# Why this hook exists: ASA writes RCONPort=<n> under [ServerSettings] of
# GameUserSettings.ini at first boot, which is enough for the port to bind
# but the server silently refuses to respond to Source-RCON AUTH packets.
# Adding a duplicate RCONPort line under [SessionSettings] fixes it — a
# real, reproducible ASA quirk (hit with raw Python + the image's bundled
# rcon-cli, not panel-specific). Verified working on princess 2026-04-22.
#
# The hook: (a) waits up to 3 min for the ini to exist (cold first-boot
# SteamCMD install can take 15-30 min but the ini is written well before
# ASA launches), (b) bails out if the [SessionSettings] RCONPort already
# exists (idempotent — subsequent starts are no-ops), (c) injects the
# line, (d) signals the monitor_ark_server.sh watchdog to relaunch ASA so
# the server re-reads the patched config on its next boot cycle. The
# relaunch is the clean way — pkill is safe because the image's
# monitor_ark_server.sh is designed to re-spawn ArkAscendedServer.exe
# whenever it dies.
lifecycle:
  post_start:
    - |
      set -e
      LAUNCH="/usr/games/scripts/launch_ASA.sh"
      INI="/usr/games/.wine/drive_c/POK/Steam/steamapps/common/ARK Survival Ascended Dedicated Server/ShooterGame/Saved/Config/WindowsServer/GameUserSettings.ini"
      WINEPREFIX_DIR="/usr/games/.wine"
      CA_MARKER="$WINEPREFIX_DIR/.panel-amazon-roots-installed-v1"
      changed=0
      # ----- Fix 1: launch_ASA.sh URL is missing ?QueryPort= -----
      # The acekorneya image hard-codes "?Port=${ASA_PORT}" in the launch
      # URL but never appends "?QueryPort=", so every sibling ARK instance
      # defaults to 27015 — only the first to bind wins, the rest have
      # NO query port. Without a query port, EOS / Steam server browser
      # can't advertise the server, so clients can't connect.
      # Idempotent: a second run sees the marker comment and no-ops.
      if [ -f "$LAUNCH" ] && ! grep -q 'QueryPort=\${QUERY_PORT' "$LAUNCH"; then
        echo "[panel-hook] patching $LAUNCH to add ?QueryPort=\${QUERY_PORT}"
        sed -i 's|?Port=${ASA_PORT}|?Port=${ASA_PORT}?QueryPort=${QUERY_PORT}|' "$LAUNCH"
        changed=1
      fi
      # ----- Fix 2: GameUserSettings.ini RCONPort under [SessionSettings] -----
      # ARK ASA's RCON server silently rejects AUTH unless RCONPort also
      # appears under [SessionSettings] (verified on princess 2026-04-22).
      # ASA accepts the launch-URL ?RCONPort=N for binding, but the
      # adapter handshake also reads from this INI key.
      for i in $(seq 1 180); do [ -f "$INI" ] && break; sleep 1; done
      if [ -f "$INI" ] && ! awk '/^\[SessionSettings\]/{f=1; next} /^\[/{f=0} f && /^RCONPort=/{found=1} END{exit !found}' "$INI"; then
        echo "[panel-hook] injecting RCONPort=${RCON_PORT:-27020} under [SessionSettings]"
        awk -v port="${RCON_PORT:-27020}" '/^\[SessionSettings\]/{print; print "RCONPort=" port; next} {print}' "$INI" > "${INI}.new"
        mv "${INI}.new" "$INI"
        changed=1
      fi
      # ----- Fix 3: pin EOS-advertised IP via -PublicIPForEpic ----------------
      # WHY: ASA's EOS session registration auto-detects the host's outbound
      # IP each time it re-registers. Under Docker host-net with multiple
      # interfaces (docker0, br-*, IPv6 link-local) EOS sometimes picks the
      # wrong adapter on a re-register and advertises an unreachable IP to
      # the in-game browser → "server invisible but RCON works" + "restart
      # fixes it" pattern. ASA exposes -PublicIPForEpic=<ipv4> to override.
      # Reference: Epic dev-forum confirmation (multihome → wrong-EOS-IP).
      # Idempotent: marker on the wine binary line means we only inject once.
      if [ -n "$PUBLIC_IP_FOR_EPIC" ] && [ -f "$LAUNCH" ] && ! grep -q -- '-PublicIPForEpic=' "$LAUNCH"; then
        echo "[panel-hook] injecting -PublicIPForEpic=${PUBLIC_IP_FOR_EPIC} into $LAUNCH"
        # Insert the flag right after the ArkAscendedServer.exe binary path.
        # The launch line ends with a backslash continuation, so the next
        # line (the URL + extra args) is unaffected.
        sed -i 's|ArkAscendedServer.exe" \\$|ArkAscendedServer.exe" -PublicIPForEpic='"${PUBLIC_IP_FOR_EPIC}"' \\|' "$LAUNCH"
        changed=1
      fi
      # ----- Fix 4: ensure system CA bundle is up-to-date (idempotent) -------
      # WHY: EOS endpoints (*.epicgames.dev, *.on.epicgames.com) are on AWS
      # CloudFront and chain to Amazon Root CA 1-4 + Starfield Services G2.
      # Whether the EOS SDK under Wine uses Wine's HKLM root store or the
      # statically-linked openssl/curl bundle inside the game, missing CAs
      # in the system bundle have been correlated with hours-later EOS
      # token-refresh failures (session ages out → server vanishes from
      # in-game browser → container restart fixes by replaying cached auth).
      # Reference: acekorneya/Ark-Survival-Ascended-Server#8 (open).
      # The acekorneya image's Debian base lists the Amazon PEMs as enabled
      # in /etc/ca-certificates.conf but may have a stale bundle if
      # update-ca-certificates didn't run during image build. Marker file
      # makes this once-per-prefix-lifetime — the run itself is ~1s if
      # nothing needs rebuilding, so the marker is just for log noise.
      if [ ! -f "$CA_MARKER" ]; then
        echo "[panel-hook] running update-ca-certificates to refresh system CA bundle"
        if update-ca-certificates >/dev/null 2>&1; then
          echo "[panel-hook]   system CA bundle refreshed"
          touch "$CA_MARKER" 2>/dev/null || true
        else
          echo "[panel-hook]   warn: update-ca-certificates failed (non-fatal)"
        fi
      fi
      if [ "$changed" = "1" ]; then
        # Relaunch ASA so it picks up the new launch script + INI. The
        # image's monitor_ark_server.sh spots the missing PID within ~60s
        # and respawns ArkAscendedServer.exe with the fixed config.
        pkill -f ArkAscendedServer.exe 2>/dev/null || true
        echo "[panel-hook] fixups applied; ASA will relaunch via image monitor"
      else
        echo "[panel-hook] all fixups already in place — no-op"
      fi

resources:
  min_ram_mb: 12288
  recommended_ram_mb: 16384

# What gets archived when an operator clicks Back-up-now. Without this
# the agent tarballs the whole 18 GB ASA install (game binaries +
# Proton runtime + saves), which is wasteful — the only files that
# actually need preserving are under ShooterGame/Saved/. Cluster
# transfers live in a sibling clusters/ dir which IS bind-mounted to
# a shared volume on cluster setup, so we exclude that — restoring
# saves shouldn't clobber cluster data the other servers are using.
backup:
  # Paths are RELATIVE to browseable_root (which is already
  # ".../ShooterGame/Saved"), NOT relative to the container root. The
  # earlier "ShooterGame/Saved/SavedArks" form pointed at a doubled path
  # that doesn't exist, so every include filtered out and busybox tar
  # got an empty stdin → exited non-zero → "sidecar exited 1".
  include:
    - "SavedArks"      # world saves (the main thing)
    - "Config"         # GameUserSettings.ini, Game.ini
    - "Logs"           # tribe logs, server logs
  exclude:
    - "clusters"               # shared volume; restoring it would clobber siblings
    - "SavedArks/*/Mods"       # mod cache; rebuilds on next start
    - "Crashes"                # crash dumps — never useful in a restore
  notes: "Saves + configs + tribe logs (~250 MB typical). Game install + Proton runtime are preserved by SteamCMD on next start; no need to back them up."

rcon:
  adapter: docker_exec_rcon
  host_port: rcon
  auth: password
  # Source-of-truth precedence (highest first, per agent's resolveRCONAddress + tracker):
  #   1. config_values["rcon_password"] — explicit override (rare)
  #   2. config_values["SERVER_ADMIN_PASSWORD"] via password_secret —
  #      the env we set at create time. THIS is what actually works
  #      for the acekorneya image.
  #   3. password_from_ini lazy-read at dial time — only effective
  #      AFTER the operator changes the password via the Config tab
  #      and the server has restarted to pick it up.
  #
  # Why both: the acekorneya image takes SERVER_ADMIN_PASSWORD and
  # passes it on the launch command line as `?ServerAdminPassword=...`.
  # ARK SA accepts the launch-arg version BUT does NOT write it back
  # into GameUserSettings.ini's [ServerSettings]ServerAdminPassword
  # — that key stays empty until the operator edits it. So the env
  # value is the working credential. The INI fallback is for after
  # the operator has changed the password via the Config tab (which
  # writes to the INI but doesn't propagate back into the env).
  password_secret: SERVER_ADMIN_PASSWORD
  password_from_ini:
    file: "/usr/games/.wine/drive_c/POK/Steam/steamapps/common/ARK Survival Ascended Dedicated Server/ShooterGame/Saved/Config/WindowsServer/GameUserSettings.ini"
    section: ServerSettings
    key: ServerAdminPassword
  commands:
    list_players: "ListPlayers"
    say:          "ServerChat {msg}"
    broadcast:    "Broadcast {msg}"
    kick:         "KickPlayer {player}"
    ban:          "BanPlayer {player}"
    save:         "SaveWorld"
    shutdown:     "DoExit"
    give_item:    "GiveItemToPlayer {player} {item} {qty} 1 0"
    set_time:     "SetTimeOfDay {time}"

state_sources:
  - type: rcon
    command: "ListPlayers"
    every: 30s
    parse:
      kind: regex
      pattern: '^(?P<index>\d+)\.\s+(?P<name>.+?),\s+(?P<steamid>\d+)'
      fields:
        players_online: index
  - type: log_tail
    files:
      - "$DATA_PATH/logs/*.log"
      - "/home/pok/arkserver/ShooterGame/Saved/Logs/ShooterGame.log"

events:
  join:
    pattern: "(?P<name>[^ ]+) joined"
    kind: join
  leave:
    pattern: "(?P<name>[^ ]+) left"
    kind: leave
  chat:
    pattern: "Chat: \\[(?P<name>[^\\]]+)\\] (?P<msg>.+)"
    kind: chat

# The panel manifest validator requires at least one update_provider. For
# ARK: SA the *real* update path is the image's built-in SteamCMD loop
# (env UPDATE_SERVER=TRUE). The stub below exists so the manifest loads;
# don't rely on it — the install path won't match the image's expected
# layout so running the panel's SteamCMD sidecar against it is a no-op at
# best. Click "Restart" instead; that triggers the image's update cycle.
update_providers:
  - id: builtin
    kind: steamcmd
    app_id: "2430930"
    install_path: "/usr/games/.wine/drive_c/POK/Steam/steamapps/common/ARK Survival Ascended Dedicated Server"

# --- Manifest-driven UI metadata (WI-07) --------------------------
# Consumed by the CONTROLLER/dashboard only (the controller loads its
# own ./modules copy at startup); the agent ignores these at runtime.
# ready_pattern is a JavaScript regex (slash-delimited when it needs
# flags) moved verbatim from the dashboard's READY_PATTERNS map.
ready_pattern: '/Server has completed startup and is now advertising/i'
appearance:
  emoji: "🦖"
  grad: "linear-gradient(135deg,#3a2e1e,#d97706)"
  art: "/game-art/ark-sa.jpg"
  steam: "2430930"