================================================================
                RYZOM DEVELOPER ENVIRONMENT  (RDE)
                  Build · Debug · Play · Forge
================================================================

A Docker-based development environment for the Ryzom MMO client.
Compile your own client, debug it with gdb, and launch it — all
from a single interactive menu in the terminal. No host-side dev
toolchain required; everything happens in a reproducible container.


----------------------------------------------------------------
TABLE OF CONTENTS
----------------------------------------------------------------

  1.  What you get
  2.  System requirements
  3.  Installation (extract & set up)
  4.  First run — building the client for the first time
  5.  Everyday use — patcher and launching the game
  6.  Build modes (stable / branch / local)
  7.  Build types (Release / RelWithDebInfo / Debug)
  8.  Auto-login (account + password)
  9.  Debugging with gdb
  10. CMake feature flags
  11. Cleaning the build cache
  12. Command-line use (non-interactive)
  13. Desktop shortcut
  14. File and directory layout
  15. Configuration file (.ryzom-config)
  16. Troubleshooting
  17. Updating RDE itself
  18. Advanced — tweaking the build
  19. Technical details
  20. License & support


================================================================
1. WHAT YOU GET
================================================================

A directory containing:

  * ryzom.sh                 — the launcher menu (you run this)
  * Dockerfile               — recipe for the build container
  * docker-compose.yml       — wires the container together
  * docker-scripts/          — scripts that run inside the container
      build-ryzom.sh         — the actual cmake/make pipeline
  * README.txt               — this file

After your first build, you also get:

  * output/                  — your built client and tools
  * .ryzom-config            — your saved settings (auto-created)
  * docker-compose.override.yml  — auto-generated per build

The launcher is the only thing you need to interact with. It
takes care of generating the override file, calling docker, and
running the client / patcher / debugger.


================================================================
2. SYSTEM REQUIREMENTS
================================================================

Operating system
----------------
  * Linux (any modern distribution: Ubuntu, Debian, Fedora,
    Arch, openSUSE, …).
  * Not tested on macOS or WSL2 — should work in principle, but
    OpenGL passthrough for the client is Linux-specific.

Software
--------
  * Docker Engine 20.10 or newer
  * Docker Compose v2 ('docker compose' subcommand) OR the
    legacy 'docker-compose' standalone command — RDE detects
    whichever is available.
  * gdb (only if you want to use the Debug menu)
  * bash 4.3+ (any modern Linux ships this)

Hardware
--------
  * ~10 GB free disk space:
      ~5 GB for the Docker image + base dependencies
      ~3 GB for the source clone + build cache
      ~2 GB for the built client and downloaded game data
  * 4 GB RAM minimum, 8 GB+ recommended for parallel compilation
  * Multi-core CPU strongly recommended — the build is heavily
    parallelizable

Network
-------
  * Internet access during the *first* build (downloads ~3 GB
    worth of dependencies, source code, and SDKs).
  * Subsequent builds work offline as long as you don't switch
    branches.


================================================================
3. INSTALLATION
================================================================

3.1  Extract the tarball
------------------------
Place the archive somewhere convenient and extract it:

    cd ~/dev                            # or wherever you keep projects
    tar xzf ryzom-dev-environment.tar.gz
    cd ryzom-dev-environment            # or whatever directory was created

3.2  Make the launcher executable
---------------------------------
On many systems the executable bit survives extraction; if not:

    chmod +x ryzom.sh docker-scripts/build-ryzom.sh

3.3  Verify Docker
------------------
Make sure your user can talk to the Docker daemon without sudo.
A quick check:

    docker compose version
    docker ps

If 'docker ps' fails with "permission denied", add yourself to
the docker group and log out / back in:

    sudo usermod -aG docker "$USER"
    # log out, log back in, then verify with `docker ps` again

If 'docker compose version' is not found but 'docker-compose'
is, that also works — RDE supports both.

3.4  (Optional) Install gdb
---------------------------
Only needed if you want to debug crashes:

    # Debian / Ubuntu
    sudo apt install gdb

    # Fedora
    sudo dnf install gdb

    # Arch
    sudo pacman -S gdb


================================================================
4. FIRST RUN — BUILDING THE CLIENT
================================================================

From the project directory, just run:

    ./ryzom.sh

You will see the main menu:

    ╔══════════════════════════════════════════════════╗
    ║    R Y Z O M   D E V   E N V I R O N M E N T     ║
    ║           build · debug · play · forge           ║
    ╚══════════════════════════════════════════════════╝

    Current settings:
      Mode         stable
      Branch       main/atys-live
      Repository   https://gitlab.com/ryzom/ryzom-core.git
      Build type   Release (no debug symbols)
      Jobs         8
      Auto-login   off
      CMake flags  all defaults

      Build output: none yet (run 'Build' first)

    What do you want to do?

      1) Build client
      2) Run patcher (update game data)
      3) Launch client
      4) Patcher + Launch
      …

Pick option **1** to start the build. You will see Docker output
in the terminal:

  * For the very first run, Docker pulls the Steam Runtime SDK
    base image and builds the dependency layer (Lua, Luabind,
    Breakpad, libsquish). This takes 10–30 minutes depending on
    your connection and machine.
  * Then the source clone happens (~1 GB).
  * Then cmake configures and make builds. This takes another
    20–60 minutes the first time.

Total first-run time: typically **30 to 90 minutes**.

When the build finishes you should see:

    >>> Build finished.

    Press any key to continue...

Press a key to return to the menu. The 'Build output' line at
the top should now read:

      Build output: available in output/

Subsequent builds reuse Docker's image cache and CMake's build
cache — incremental builds typically take 1–5 minutes.


================================================================
5. EVERYDAY USE
================================================================

After the build is done, you have three things you can do from
the main menu:

  2) Run patcher              — fetches/updates game data
  3) Launch client            — starts the client
  4) Patcher + Launch         — does both, equivalent to old
                                start.sh

5.1  First time playing
-----------------------
The first time you run the client there is no game data on disk
yet. Use option **2 (Run patcher)** first — this will download
several GB of game data. Then use option **3** to launch.

For all subsequent sessions, option **4 (Patcher + Launch)** is
the canonical "play the game" option: it briefly checks for data
updates, then launches the client.

5.2  Where the client runs
--------------------------
The client always runs in the foreground of the same terminal.
The launcher is "blocked" while the game is running — that's
intentional. To get back to the menu, exit the game.

If you want to keep using your terminal while the client runs,
either start it from a separate terminal, or background it:

    ./ryzom.sh launch &

(Note: for the gdb-attach workflow described below, you _need_
a separate terminal anyway.)


================================================================
6. BUILD MODES
================================================================

RDE supports three modes for managing the source tree, switched
under Settings → Mode:

6.1  stable  (default)
----------------------
Tracks the upstream branch exactly. On every build:
  * If the source isn't cloned yet, clone it.
  * Fetch from origin.
  * Hard-reset the working tree to origin/<branch>.

⚠ This mode **destroys** any local changes you made to the
source tree. Use it when you want a clean, reproducible build
of the official code.

6.2  branch
-----------
Like 'stable' but **without** the hard-reset:
  * Clone if missing.
  * Fetch from origin.
  * Checkout the configured branch.
  * Local commits and uncommitted changes are kept.

Use this when you have your own branch on a fork and you want
to track it without losing local edits.

6.3  local
----------
RDE doesn't touch git at all. Instead it bind-mounts a directory
from your host into the container. You set the path under
Settings → Local source dir.

Setup:

  1. Clone ryzom-core somewhere on your host:

       git clone https://gitlab.com/ryzom/ryzom-core.git ~/dev/ryzom-core

  2. In RDE: Settings → Mode → 3 (local)
  3. Settings → Local source dir → /home/you/dev/ryzom-core

Now you can work on the source from your host (in your IDE,
your editor, with your git tools) and every RDE build sees
your latest state. This is the recommended mode for active
development.

⚠ Switching modes invalidates the CMake cache. After switching,
clean the build cache (Main menu → Clean → 1) before rebuilding.


================================================================
7. BUILD TYPES
================================================================

Switch under Settings → Build type. Each type has its own
build cache directory inside the container, so you can switch
back and forth without losing work.

  Release         Optimized, minimal symbols. Smallest binary,
                  fastest. Default. Use for normal play.

  RelWithDebInfo  Optimized + full debug symbols. Same speed as
                  Release but ~3x larger. Use this whenever you
                  want to debug a crash with gdb. This is the
                  recommended build type for development.

  Debug           Unoptimized + symbols + asserts on. Much slower,
                  but you can step through code line by line. Use
                  for serious investigation of weird bugs.

Switching build types does NOT require a clean — each type has
its own cache under /build/release, /build/relwithdebinfo, and
/build/debug inside the container.


================================================================
8. AUTO-LOGIN
================================================================

The Ryzom client accepts the account name and password as the
first two positional arguments:

    ./ryzom_client_dev <account> <password>

RDE can store these and pass them automatically on every launch.

8.1  Setup
----------
  1. Settings → Account            → enter your account name
  2. Settings → Password           → enter password (input is hidden)
  3. Settings → Auto-login         → toggle to ON

The status line will then show:

    Auto-login   ON (account: your_name)

Once on, the main menu adds two extra options:

    3)  Launch client (auto-login as your_name)
    3m) Launch client (manual — show login screen)
    4)  Patcher + Launch (auto-login)
    4m) Patcher + Launch (manual)

Use the 'm' suffix when you want to log in with a different
account once without disabling auto-login in settings.

8.2  Security note
------------------
Your password is stored in plain text in '.ryzom-config'. RDE
sets the file permissions to 600 (owner-only readable) on every
save, but it is still plain text on disk.

  ✔ Add .ryzom-config to your .gitignore (always).
  ✔ Don't sync this directory via Dropbox/Google Drive without
    encryption.
  ✗ Never commit .ryzom-config to a public repository.

When the password is shown anywhere in RDE (status, settings,
command transcript), it is replaced by '(set)' or '<password>'.
The real value is only used at the moment the client is exec'd.

8.3  CLI override
-----------------
On the command line you can skip auto-login for one launch:

    ./ryzom.sh launch --no-auto
    ./ryzom.sh play   --no-auto
    ./ryzom.sh gdb    --no-auto

Useful for debugging or for switching accounts temporarily.


================================================================
9. DEBUGGING WITH GDB
================================================================

The Debug submenu (Main menu → 5) gives you two ways to run
the client under gdb. Both require gdb installed on your host.

9.1  Launch under gdb
---------------------
Starts the client directly under gdb. When the client crashes,
gdb pauses and you get a prompt where you can inspect what
went wrong. Typical workflow:

  1. Settings → Build type → RelWithDebInfo (so symbols exist)
  2. Build client
  3. Debug → 1 (Launch under gdb)
  4. Play until the crash happens
  5. At the (gdb) prompt:

         (gdb) bt              ← backtrace of the crashing thread
         (gdb) bt full         ← backtrace with local variables
         (gdb) info threads    ← what other threads were doing
         (gdb) thread apply all bt   ← backtrace every thread
         (gdb) print someVar   ← inspect a value
         (gdb) quit            ← exit (kills the program)

The full command being executed is shown in the terminal
transcript right before gdb starts, so you can see exactly
what RDE is doing.

9.2  Attach to a running client
-------------------------------
Useful when:
  * The client is hanging and you want to see what thread is stuck
  * You want to inspect state mid-game
  * The crash is hard to reproduce, so you keep it running

How it works:

  1. Start the client in *another* terminal:

       ./ryzom.sh launch          # in terminal A

  2. In *this* terminal:

       ./ryzom.sh attach          # in terminal B
     or via the menu: Debug → 2

RDE first looks for your dev build (ryzom_client_dev). If that
isn't running, it falls back to searching for any official
ryzom client binary (ryzom_client_r, ryzom_client, …). If
multiple processes are found you get a picker:

    Found 2 ryzom process(es):

      1) PID 4321 runtime 01:23:45 /opt/.../ryzom_client_r  (other binary — likely stripped)
      2) PID 4399 runtime 00:00:08 /home/.../ryzom_client_dev (your dev build — has symbols)

    Pick a number (or 'b' to cancel):

When attaching to a non-dev binary, RDE warns you that
backtraces will only show memory addresses, not function
names — see section 9.4.

9.3  Common gdb commands
------------------------
At the (gdb) prompt:

  continue    or  c        Resume execution
  bt                       Backtrace of current thread
  bt full                  Backtrace + local variable values
  info threads             List all threads
  thread N                 Switch to thread N
  thread apply all bt      Backtrace of every thread
  frame N                  Jump to stack frame N
  print <expr>             Evaluate any C++ expression
  list                     Show source code at current location
  quit    or  q            Exit gdb (will kill the program)

To detach without killing:

  detach                   Leave the program running
  quit                     Confirms detach if you forgot to detach

9.4  Stripped binaries (official client)
----------------------------------------
The official Ryzom client (downloaded by the patcher) has its
debug symbols stripped. You can still attach gdb to it, but:

  ✘ 'bt' shows hex addresses instead of function names
  ✘ 'print someVar' won't know what variables exist
  ✘ Source-level stepping doesn't work

Still useful:
  ✔ 'info threads'              — count and state of threads
  ✔ 'info sharedlibrary'        — list all loaded .so files
  ✔ 'thread apply all bt'       — see what every thread is on
                                  (raw addresses but you can spot
                                  deadlocks, infinite loops, etc.)

Workaround: if you have a matching dev build, you can
manually load symbols from your local .so files:

    (gdb) add-symbol-file /home/you/.../output/lib/libnel3d.so

This works _if_ your dev build is reasonably close to the
official binary's source version. Mismatched versions may give
nonsense symbols. The cleaner approach for serious debugging
is to reproduce the issue with your own dev build.

9.5  Breakpad minidumps
-----------------------
If WITH_BREAKPAD is on (default), the client writes a small
crash dump file when it crashes. These minidumps can be
analyzed offline with Breakpad's tools — very useful when a
crash isn't reproducible. RDE doesn't (yet) provide a wrapper
for this; see breakpad's documentation.

9.6  ptrace_scope gotcha
------------------------
Modern Linux distros restrict ptrace by default. If 'attach'
fails with "Operation not permitted" even on your own process:

    sudo sysctl -w kernel.yama.ptrace_scope=0

This lasts until reboot. To make it permanent, edit
/etc/sysctl.d/10-ptrace.conf accordingly.


================================================================
10. CMAKE FEATURE FLAGS
================================================================

Settings → 9 (CMake flags...) opens a submenu where you can
toggle each feature flag between ON and OFF. Defaults:

  WITH_RYZOM_CLIENT          ON   build the main game client
  WITH_RYZOM_LIVE            ON   live (atys) configuration
  WITH_RYZOM_CLIENT_PATCHER  ON   build the patcher binary
  WITH_RYZOM_PATCH           ON   patch creation tools
  WITH_RYZOM_TOOLS           OFF  ryzom utility tools (mesh, sound, …)
  WITH_NEL_TOOLS             OFF  NeL utility tools
  WITH_NEL_TESTS             OFF  NeL unit tests (slow)
  WITH_NEL_SAMPLES           OFF  NeL sample programs
  WITH_BREAKPAD              ON   crash reporter
  WITH_PCH                   OFF  precompiled headers (faster
                                  builds, occasionally flaky)

In the submenu, type a number to toggle, 'r' to reset all to
defaults, or 'b' to go back. Modified flags are marked with a
yellow asterisk so you can see at a glance what you've changed.

The main menu's settings section also shows which flags differ
from defaults:

  CMake flags  WITH_NEL_TOOLS=ON, WITH_PCH=ON

⚠ After toggling a flag and rebuilding for the first time,
CMake might still use cached values. If your change doesn't
seem to take effect, clean the build cache (Clean → 1) and
rebuild.


================================================================
11. CLEANING THE BUILD CACHE
================================================================

Main menu → 7 (Clean) gives you three options:

  1) Build cache only        — wipes /build/* in the container.
                               Forces CMake to re-configure on
                               the next build. Source clone is
                               kept.
                               Use this after switching mode,
                               toggling a flag, or when the build
                               misbehaves in a weird way.

  2) Output binaries         — clears the host-side output/
                               directory. Doesn't touch the
                               build cache. Use when you want
                               to ensure 'output/' only contains
                               files from the latest build.

  3) Everything              — runs 'docker compose down -v',
                               which removes BOTH the source
                               clone volume AND the build cache.
                               Equivalent to a fresh first-run
                               state. Use as a last resort.

Option 3 with 'stable' or 'branch' mode means the next build
re-downloads ~1 GB of source. Use sparingly.


================================================================
12. COMMAND-LINE USE (NON-INTERACTIVE)
================================================================

All menu actions have CLI equivalents. Useful for scripting and
desktop shortcuts. Settings are read from .ryzom-config (so set
them via the menu first).

    ./ryzom.sh                       # interactive menu
    ./ryzom.sh build                 # build with saved settings
    ./ryzom.sh patch                 # run patcher
    ./ryzom.sh launch                # launch the client
    ./ryzom.sh launch --no-auto      # launch without auto-login
    ./ryzom.sh play                  # patcher + launch (use this
                                     # for desktop shortcuts)
    ./ryzom.sh play --no-auto        # patcher + launch, no auto-login
    ./ryzom.sh gdb                   # launch under gdb
    ./ryzom.sh gdb --no-auto         # gdb, manual login
    ./ryzom.sh attach                # attach gdb to running client
    ./ryzom.sh status                # print current settings
    ./ryzom.sh --help                # show all commands

Exit codes:
    0    success
    1    runtime error (missing binary, no process, etc.)
    2    invalid command-line arguments


================================================================
13. DESKTOP SHORTCUT
================================================================

To launch Ryzom from your desktop or application launcher,
create a .desktop file at ~/.local/share/applications/ryzom.desktop:

    [Desktop Entry]
    Type=Application
    Name=Ryzom (Dev)
    Comment=Launch the self-built Ryzom client
    Exec=/home/you/dev/ryzom-dev-environment/ryzom.sh play
    Icon=/home/you/dev/ryzom-dev-environment/icon.png
    Terminal=true
    Categories=Game;

Adjust the paths. Set Terminal=true so output is visible (and
gdb-attach has a terminal to talk to in case of a crash).

You can also create a second shortcut for "manual login" mode:

    Exec=/home/you/dev/ryzom-dev-environment/ryzom.sh play --no-auto


================================================================
14. FILE AND DIRECTORY LAYOUT
================================================================

After installation and a first build, your project directory
looks like this:

  ryzom-dev-environment/
  ├── ryzom.sh                      # the launcher (you run this)
  ├── Dockerfile                    # build container recipe
  ├── docker-compose.yml            # compose configuration
  ├── docker-compose.override.yml   # auto-generated per build
  ├── docker-scripts/
  │   └── build-ryzom.sh            # build pipeline (runs in container)
  ├── .ryzom-config                 # your saved settings (chmod 600)
  ├── output/                       # build artifacts
  │   ├── ryzom_client_dev          # your built client
  │   ├── ryzom_client_patcher      # the patcher
  │   ├── tools/                    # NeL/Ryzom tools (if enabled)
  │   ├── lib/                      # bundled .so libraries
  │   └── data/                     # downloaded game data (after patcher)
  └── README.txt                    # this file

What you should NOT commit to version control:
  * .ryzom-config         (contains your password)
  * docker-compose.override.yml  (auto-generated, host-specific)
  * output/               (build artifacts)
  * (don't bother with build cache — it lives in Docker volumes)

A reasonable .gitignore:

    .ryzom-config
    docker-compose.override.yml
    output/

Inside the Docker container (only matters for advanced use):
  * /src/ryzom-core   — source clone (or bind-mount in 'local' mode)
  * /build/release    — Release build cache
  * /build/relwithdebinfo — RelWithDebInfo build cache
  * /build/debug      — Debug build cache
  * /output           — bind-mount of host's output/ directory


================================================================
15. CONFIGURATION FILE
================================================================

RDE saves your settings to .ryzom-config. Format is plain bash:

    RYZOM_MODE="local"
    RYZOM_BRANCH="main/atys-live"
    RYZOM_REPO="https://gitlab.com/ryzom/ryzom-core.git"
    JOBS="8"
    LOCAL_SRC_PATH="/home/you/dev/ryzom-core"
    BUILD_TYPE="RelWithDebInfo"
    RYZOM_ACCOUNT="your_name"
    RYZOM_PASSWORD='your_password'
    AUTO_LOGIN="on"

    # CMake feature flag overrides (only those changed from defaults)
    CMAKE_FLAG_WITH_NEL_TOOLS="ON"
    CMAKE_FLAG_WITH_PCH="ON"

You can edit this file by hand if you prefer — RDE re-reads it
on every start. Just make sure to keep the chmod 600 if it
contains a password (RDE will re-apply 600 on the next save
through the menu).

Only modified CMake flags are saved. This means: if a future
RDE update changes a default, you automatically get the new
default unless you explicitly overrode it.


================================================================
16. TROUBLESHOOTING
================================================================

16.1  "permission denied" running ryzom.sh
------------------------------------------
The launcher isn't executable. Fix:

    chmod +x ryzom.sh docker-scripts/build-ryzom.sh

16.2  "Cannot connect to the Docker daemon"
-------------------------------------------
Docker isn't running, or your user isn't in the 'docker' group.

    sudo systemctl start docker
    sudo usermod -aG docker "$USER"
    # log out, log back in

16.3  "neither 'docker compose' nor 'docker-compose' is available"
------------------------------------------------------------------
You have Docker but not the Compose plugin. On Debian/Ubuntu:

    sudo apt install docker-compose-plugin

On Fedora:

    sudo dnf install docker-compose

16.4  Output files owned by root
--------------------------------
RDE auto-detects the host UID by stat'ing the output/ directory
itself, so this should not happen. If it does, the most likely
cause is that the directory was deleted while the container was
running. Fix:

    sudo chown -R "$USER:$USER" output/

16.5  Container name conflict
-----------------------------
Symptom:

    Error response from daemon: Conflict. The container name
    "/ryzom-builder" is already in use ...

Cause: a previous build was interrupted (Ctrl-C, terminal
closed) and Docker left a stopped container behind. RDE
removes stale containers automatically before each build, but
if it still bites you:

    docker rm -f ryzom-builder

16.6  "no space left on device"
-------------------------------
Docker volumes can grow quickly. Check usage:

    docker system df

Free space:

    docker system prune -a       # removes unused images
    docker volume prune          # removes unused volumes

⚠ 'docker system prune -a' will also delete the RDE base image,
forcing the next build to re-pull (~3 GB).

16.7  "Build cache out of date" / strange CMake errors
------------------------------------------------------
Switching mode, branch, or toggling a flag can confuse CMake's
cache. Fix:

    Main menu → Clean → 1 (Build cache only)

Then rebuild.

16.8  Build fails pulling the Steam Runtime image
-------------------------------------------------
The base image is hosted at registry.gitlab.steamos.cloud.
Check that you can reach it:

    curl -I https://registry.gitlab.steamos.cloud

If your network blocks this (corporate firewall, ISP issues),
try a different network or a VPN.

16.9  First build is unbearably slow
------------------------------------
Expected. The first build pulls ~3 GB of base layers and
compiles every dependency from source. Subsequent builds use
caches and are typically 1–5 minutes for incremental changes.

If you have a beefy CPU but the build still feels CPU-bound,
make sure JOBS is set to your core count:

    Settings → Parallel jobs → 16   (or whatever you have)

16.10  Client crashes immediately at launch
-------------------------------------------
First, run the patcher (option 2) to make sure game data is
present and up to date. If that doesn't help:

  * Try Build type 'RelWithDebInfo' and run under gdb to see
    the actual crash location.
  * Check that your GPU drivers support OpenGL legacy (the
    client uses OpenGL 2.x via fixed-function pipeline).
  * Check console output for missing-library errors — those
    indicate a bundling bug; report it.

16.11  gdb fails with "version `CURL_OPENSSL_4' not found"
----------------------------------------------------------
This was a bug in older RDE versions where LD_LIBRARY_PATH
was set for gdb itself. Fixed in current versions — if you see
this, you have an outdated ryzom.sh. Update RDE.

16.12  "ryzom_client_dev not found in output/"
----------------------------------------------
You haven't built yet, or the build was incomplete. Run a
clean build:

    Main menu → Clean → 1 (Build cache only)
    Main menu → 1 (Build client)

If WITH_RYZOM_CLIENT was accidentally turned off, the build
will succeed but produce no client. Check Settings → CMake
flags and make sure WITH_RYZOM_CLIENT is ON.

16.13  Auto-login set up but client still shows login screen
------------------------------------------------------------
Possible causes:

  * AUTO_LOGIN is 'off' — check Settings → Auto-login
  * Account or password is empty — check Settings shows
    "ON (account: <name>)" not "ON but credentials missing"
  * You used 3m / 4m / --no-auto, which forces manual login
  * The wrong character name is selected on the server side
    (auto-login passes account+password, not the character
    selection — that still happens after login)

16.14  pgrep / attach finds nothing even though the client is running
---------------------------------------------------------------------
RDE scans /proc/*/exe directly so the 15-character comm
truncation isn't an issue. If attach genuinely finds nothing:

  * Make sure the client was started by your own user (you
    can't see /proc/PID/exe of other users without root).
  * The binary basename must match one of: ryzom_client_dev,
    ryzom_client_r, client_ryzom_r, ryzom_client. If you renamed
    it, attach won't find it.

16.15  How do I completely start over?
--------------------------------------
Nuclear option:

    Main menu → Clean → 3 (Everything)
    rm -f .ryzom-config docker-compose.override.yml
    docker rmi ryzom-client-builder:latest

Then run ./ryzom.sh again as if it were the first time.


================================================================
17. UPDATING RDE ITSELF
================================================================

When a new tarball arrives:

  1. Save your current settings if you want to keep them:

         cp .ryzom-config /tmp/ryzom-config.backup

  2. Extract the new tarball into a new directory:

         cd ~/dev
         tar xzf ryzom-dev-environment-NEW.tar.gz

     (Or extract over the old one if you trust the update.)

  3. Restore your settings:

         cp /tmp/ryzom-config.backup ryzom-dev-environment-NEW/.ryzom-config

  4. Run ./ryzom.sh — it will use your previous settings.

If the Dockerfile changed, the next build automatically
rebuilds the image (Docker detects the diff). No manual action
needed. But this means the next build takes longer.

If the .ryzom-config format changed, RDE will fall back to
defaults for any keys it doesn't recognize. Settings you set in
the new menu will be saved correctly.


================================================================
18. ADVANCED — TWEAKING THE BUILD
================================================================

18.1  Adding a new toggleable CMake flag
----------------------------------------
Three places to edit:

  1. ryzom.sh — extend three definitions:

         CMAKE_FLAG_ORDER+=( WITH_NEW_THING )
         CMAKE_FLAG_DEFAULT[WITH_NEW_THING]="ON"
         CMAKE_FLAG_DESC[WITH_NEW_THING]="What this thing does"

  2. docker-scripts/build-ryzom.sh — add to the variable
     defaults section:

         WITH_NEW_THING="${WITH_NEW_THING:-ON}"

     and to the cmake invocation:

         -DWITH_NEW_THING="${WITH_NEW_THING}" \

  3. Build: Clean → 1, then Build.

The new flag now appears in Settings → CMake flags.

18.2  Adding a host-side dependency in the container
----------------------------------------------------
Edit Dockerfile, add the package to the apt-get install list,
then rebuild the image:

    docker compose build --no-cache ryzom-builder

The next 'Build client' run will use the new image.

18.3  Targeting a different upstream
------------------------------------
Use mode 'branch' (or 'stable'):

    Settings → Mode      → 2 (branch)
    Settings → Repository → https://gitlab.com/yourfork/ryzom-core.git
    Settings → Branch    → your-branch-name

Hard-resets are off in 'branch' mode so your local commits in
the volume survive between builds.


================================================================
19. TECHNICAL DETAILS
================================================================

  Base image
    Steam Runtime 1 'scout' SDK (registry.gitlab.steamos.cloud).
    glibc 2.15 era. Why scout? It produces a binary that runs
    on virtually any Linux from the past decade.

  Compiler
    GCC 4.8 (the version the official Ryzom toolchain uses).
    A modern CMake (3.22) is layered on top because Scout's
    bundled CMake doesn't detect OpenGL the same way.

  In-container dependencies built from source
    Lua 5.3.6 — not packaged in scout
    Luabind (nimetu fork) — for C++11 + Lua 5.3 support
    Google Breakpad — crash reporter
    libsquish 1.15 — texture compression (DXT)

  Output binary characteristics
    * Renamed from ryzom_client to ryzom_client_dev to avoid
      being overwritten by the patcher (which fetches the
      official ryzom_client binary).
    * RPATH baked in: $ORIGIN/lib  — finds bundled libs without
      LD_LIBRARY_PATH.
    * Bundled libs in output/lib/ are non-core libraries
      (NeL, Ryzom, libsquish). System libs (glibc, OpenGL,
      X11, libstdc++) are expected on the host.

  Build artifacts collected
    * ryzom_client_dev   — the client (renamed)
    * ryzom_client_patcher — the patcher (vanilla name)
    * tools/             — every other ELF executable from the
                           build tree (NeL/Ryzom utilities)
    * lib/               — NeL/Ryzom shared libraries with
                           SONAME symlinks


================================================================
20. LICENSE & SUPPORT
================================================================

This build environment is licensed under AGPLv3, same as Ryzom
Core itself.

Ryzom Core source:        https://gitlab.com/ryzom/ryzom-core
Ryzom Core wiki:          https://wiki.ryzom.dev
Official game / forum:    https://ryzom.com
Ryzom Chat:               https://chat.ryzom.com

Found a bug in RDE itself? File an issue or send a patch via
whichever channel you got the tarball from.

================================================================
                     End of README · Have fun on Atys
================================================================
