diff --git a/CLAUDE.md b/CLAUDE.md index 643d7a6..aaf165b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,6 +13,7 @@ continuity. - [docs/STYLE.md](docs/STYLE.md): the look and sound. Every client colour comes from `Palette`. - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): server-authoritative design and module map. - [src/sim/tuning.gd](src/sim/tuning.gd): the one table of gameplay numbers. +- [docs/PLAY.md](docs/PLAY.md): graphics presets, renderers and the tested configurations. ## Commands @@ -70,7 +71,9 @@ Run one group of tests with `tools/run_tests.sh --root=res://test/sim` or - **Open every capture and look at it** (the Read tool shows images). The harness only catches blank frames. A broken, ugly or misleading capture means the issue isn't done. - The default renderer is Forward+ through Mesa's Lavapipe, which matches the game. - `CAPTURE_RENDERER=compatibility` uses OpenGL through llvmpipe. Colours differ between + `CAPTURE_RENDERER=compatibility` uses OpenGL through llvmpipe, and + `CAPTURE_RENDERER=no_vulkan` hides the Vulkan driver to check the game falls back to OpenGL (H2). + The `quality_low`, `quality_medium` and `quality_high` scenarios draw a match moment with each preset. Colours differ between the two, so compare captures made with the same renderer. - Software rendering shows what is drawn, not how fast. Never report frame rates from it. diff --git a/docs/PLAY.md b/docs/PLAY.md new file mode 100644 index 0000000..962adb4 --- /dev/null +++ b/docs/PLAY.md @@ -0,0 +1,71 @@ +# Playing Tidewall on Linux + +This page covers graphics settings and the systems Tidewall has been tested on. R3 +adds the rest of the player guide (controls, rules, servers). + +## Graphics presets + +Settings → Graphics → Quality. + +| Preset | Sun shadows | Shadow cascades | 3D resolution | Anti-aliasing | +|---|---|---|---|---| +| Low | Off | n/a | 75% of the window | FXAA | +| Medium | Up to 200 m | 2 | 100% | FXAA | +| High (default) | Up to 400 m | 4 | 100% | MSAA 2x | + +No preset changes how far trees, rocks, wrecks or built pieces are drawn. A lower +preset never lets anyone see a player through cover that a higher one would still +draw. The woodcut ink lines are a separate switch on the same tab. + +`make bench` counts what a frame asks of the GPU, with High's shadows. The measured numbers are in +[ARCHITECTURE.md](ARCHITECTURE.md#performance-budgets) and the DEVLOG. + +## Renderers + +Tidewall is made for Godot's **Forward+** renderer on **Vulkan**. If Vulkan can't start +(no Vulkan driver, or a GPU too old for it), the game falls back to **OpenGL** +(Godot's Compatibility renderer) rather than crashing. The main menu then says so in +red under the motto. Everything works there, but the light, fog and sea look a little +different. Known difference: with shadows on (Medium, High) the ground and rocks come +out paler under OpenGL than under Vulkan (issue #81). + +To choose a renderer yourself: + + ./tidewall.x86_64 --rendering-method gl_compatibility # OpenGL + ./tidewall.x86_64 --rendering-method forward_plus # Vulkan (the default) + +## Display servers and GPUs + +- **X11:** the default. +- **Wayland:** by default the game runs through XWayland, which every Wayland desktop + provides. To try Godot's native Wayland support, start it with + `--display-driver wayland`. +- **Hybrid graphics (a laptop or desktop with an integrated and a discrete GPU):** + Godot's Vulkan renderer prefers the discrete GPU on its own. If the game still starts + on the integrated one, run it with the driver's offload variables, for example + `__NV_PRIME_RENDER_OFFLOAD=1 __GLX_VENDOR_LIBRARY_NAME=nvidia ./tidewall.x86_64` on + NVIDIA, or `DRI_PRIME=1 ./tidewall.x86_64` on Mesa. `--gpu-index N` picks a Vulkan + device by number. + +## Tested configurations + +Be careful reading this table. The automated tests run in a container with **software +rendering only**. They show that the game starts, draws the right picture and falls back +correctly. They say nothing about frame rates or how it feels on real hardware. That +is checked in the hands-on playtest (R6), and this table will be updated from it. + +| Configuration | Renderer | How it was tested | Result | +|---|---|---|---| +| Debian 13, Xvfb (X11), Mesa Lavapipe | Forward+ / Vulkan | Software only: every capture, all three presets (`quality_*` captures) | Draws correctly | +| Debian 13, Xvfb (X11), Mesa llvmpipe | Compatibility / OpenGL | Software only: all three presets | Draws correctly. Paler ground with shadows on (see above) | +| Debian 13, Xvfb (X11), no Vulkan driver | Falls back to OpenGL | Software only: `CAPTURE_RENDERER=no_vulkan` capture of the main menu | Falls back and shows the notice | +| Release package outside the repo, headless | None (server and autoplay client) | `make dist-check` | Plays a full match; the game joins its server | +| Wayland (native or XWayland) | Any | **Not tested** | Unknown | +| Real NVIDIA, AMD or Intel GPU | Forward+ / Vulkan | **Not tested yet** (R6) | Unknown | +| Hybrid NVIDIA and Intel desktop | Any | **Not tested yet** (R6) | Unknown | + +To reproduce the software-rendered rows: + + CAPTURE_RENDERER=forward_plus tools/capture.sh quality_high captures/q.png + CAPTURE_RENDERER=compatibility tools/capture.sh quality_low captures/q.png + CAPTURE_RENDERER=no_vulkan tools/capture.sh menu_main captures/m.png diff --git a/src/app/main.gd b/src/app/main.gd index be3d78d..a1fa371 100644 --- a/src/app/main.gd +++ b/src/app/main.gd @@ -44,6 +44,8 @@ func _ready() -> void: _start_browsing() return var windowed: bool = DisplayServer.get_name() != "headless" and not _config.autoplay + if windowed and not RendererCheck.fallback_notice().is_empty(): + print("tidewall: " + RendererCheck.fallback_notice()) if windowed and not _config.asked: # The game as a player starts it: the main menu. _open_shell() diff --git a/src/app/renderer_check.gd b/src/app/renderer_check.gd new file mode 100644 index 0000000..d8db0ca --- /dev/null +++ b/src/app/renderer_check.gd @@ -0,0 +1,28 @@ +## H2: tells the player when the game isn't drawing with the renderer it was made for. +## Tidewall asks for Forward+ on Vulkan. Where Vulkan can't start (no driver, or an old +## GPU), Godot falls back to OpenGL (Compatibility, the project's +## fallback_to_opengl3) instead of crashing, and the main menu says so. +class_name RendererCheck +extends RefCounted + +const NOTICE: String = "Vulkan isn't available here, so Tidewall is drawing with OpenGL instead. It works, but the sea and light may look a little different. An up-to-date graphics driver may bring Vulkan back." + + +## The notice for this run, or "" when the renderer is the one asked for, the player +## chose one on the command line, or nothing is drawn. +static func fallback_notice() -> String: + if DisplayServer.get_name() == "headless": + return "" + return notice_for( + String(ProjectSettings.get_setting("rendering/renderer/rendering_method", "forward_plus")), + RenderingServer.get_current_rendering_method(), + OS.get_cmdline_args()) + + +static func notice_for(wanted: String, actual: String, args: PackedStringArray) -> String: + if actual.is_empty() or actual == wanted: + return "" + for arg: String in args: + if arg.begins_with("--rendering-method") or arg.begins_with("--rendering-driver"): + return "" + return NOTICE diff --git a/src/app/renderer_check.gd.uid b/src/app/renderer_check.gd.uid new file mode 100644 index 0000000..8de3668 --- /dev/null +++ b/src/app/renderer_check.gd.uid @@ -0,0 +1 @@ +uid://duaotpjllo5rf diff --git a/src/client/game_settings.gd b/src/client/game_settings.gd index d20fc4c..faba259 100644 --- a/src/client/game_settings.gd +++ b/src/client/game_settings.gd @@ -8,16 +8,23 @@ extends RefCounted const DEFAULT_PATH: String = InputSettings.DEFAULT_PATH -## Graphics quality presets (H2 tunes what each does). +## Graphics quality presets (H2; documented in docs/PLAY.md). const QUALITY_NAMES: Array[String] = ["Low", "Medium", "High"] const QUALITY_LOW: int = 0 const QUALITY_MEDIUM: int = 1 const QUALITY_HIGH: int = 2 -## Per preset: sun shadow distance in metres (0 = no shadows) and 3D render scale. +## Per preset: +## shadow_distance how far the sun casts shadows, in metres (0 = no shadows) +## shadow_splits the sun's shadow cascades: 1, 2 or 4 +## render_scale the 3D resolution against the window's +## msaa multisample anti-aliasing (a Viewport.MSAA_ value) +## fxaa the cheap screen-space anti-aliasing, for presets without MSAA +## Nothing here changes what can be seen: trees, rocks and pieces are drawn as far on +## every preset, so a lower one never shows a player through cover. const QUALITY: Array[Dictionary] = [ - {"shadow_distance": 0.0, "render_scale": 0.75}, - {"shadow_distance": 200.0, "render_scale": 1.0}, - {"shadow_distance": 400.0, "render_scale": 1.0}, + {"shadow_distance": 0.0, "shadow_splits": 1, "render_scale": 0.75, "msaa": Viewport.MSAA_DISABLED, "fxaa": true}, + {"shadow_distance": 200.0, "shadow_splits": 2, "render_scale": 1.0, "msaa": Viewport.MSAA_DISABLED, "fxaa": true}, + {"shadow_distance": 400.0, "shadow_splits": 4, "render_scale": 1.0, "msaa": Viewport.MSAA_2X, "fxaa": false}, ] const WINDOW_MODES: Array[String] = ["Windowed", "Fullscreen", "Exclusive fullscreen"] ## Frame caps offered, 0 for none. @@ -73,6 +80,19 @@ func render_scale() -> float: return float(QUALITY[quality]["render_scale"]) +func shadow_splits() -> int: + return int(QUALITY[quality]["shadow_splits"]) + + +## Render scale and anti-aliasing on the viewport the match is drawn in. +func apply_to_viewport(viewport: Viewport) -> void: + if viewport == null: + return + viewport.scaling_3d_scale = render_scale() + viewport.msaa_3d = QUALITY[quality]["msaa"] + viewport.screen_space_aa = Viewport.SCREEN_SPACE_AA_FXAA if QUALITY[quality]["fxaa"] else Viewport.SCREEN_SPACE_AA_DISABLED + + func save(path: String = DEFAULT_PATH) -> Error: var config: ConfigFile = ConfigFile.new() # The mouse keeps its own section, as InputSettings has always saved it. @@ -133,8 +153,8 @@ func apply_to_program(tree: SceneTree) -> void: var modes: Array[DisplayServer.WindowMode] = [DisplayServer.WINDOW_MODE_WINDOWED, DisplayServer.WINDOW_MODE_FULLSCREEN, DisplayServer.WINDOW_MODE_EXCLUSIVE_FULLSCREEN] if DisplayServer.window_get_mode() != modes[window_mode]: DisplayServer.window_set_mode(modes[window_mode]) - if tree != null and tree.root != null: - tree.root.scaling_3d_scale = render_scale() + if tree != null: + apply_to_viewport(tree.root) ## Sets the Master bus, and the Music and Effects buses, making them if they aren't diff --git a/src/client/match_view.gd b/src/client/match_view.gd index c11c804..5c22951 100644 --- a/src/client/match_view.gd +++ b/src/client/match_view.gd @@ -30,6 +30,8 @@ func apply_settings(settings: GameSettings) -> void: if sun != null: sun.shadow_enabled = distance > 0.0 sun.directional_shadow_max_distance = maxf(distance, 1.0) + var splits: Dictionary = {1: DirectionalLight3D.SHADOW_ORTHOGONAL, 2: DirectionalLight3D.SHADOW_PARALLEL_2_SPLITS, 4: DirectionalLight3D.SHADOW_PARALLEL_4_SPLITS} + sun.directional_shadow_mode = splits.get(settings.shadow_splits(), DirectionalLight3D.SHADOW_PARALLEL_4_SPLITS) if print_pass != null: print_pass.visible = settings.print_pass diff --git a/src/ui/menus.gd b/src/ui/menus.gd index ac41f1a..94a9505 100644 --- a/src/ui/menus.gd +++ b/src/ui/menus.gd @@ -324,6 +324,17 @@ func _build_main() -> void: motto.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER motto.add_theme_font_size_override("font_size", FONT_SMALL) column.add_child(motto) + var fallback: String = RendererCheck.fallback_notice() + if not fallback.is_empty(): + var notice: Label = Label.new() + notice.name = "RendererNotice" + notice.text = fallback + notice.autowrap_mode = TextServer.AUTOWRAP_WORD_SMART + notice.custom_minimum_size = Vector2(460.0, 0.0) + notice.horizontal_alignment = HORIZONTAL_ALIGNMENT_CENTER + notice.add_theme_font_size_override("font_size", FONT_SMALL) + notice.add_theme_color_override("font_color", Palette.OCHRE_RED) + column.add_child(notice) _button(column, "Practice against bots", func() -> void: show_screen("practice")) _button(column, "Join a server", func() -> void: show_screen("join")) _button(column, "Settings", func() -> void: show_screen("settings")) diff --git a/test/capture/match_scene.gd b/test/capture/match_scene.gd index 76be484..fc88a05 100644 --- a/test/capture/match_scene.gd +++ b/test/capture/match_scene.gd @@ -13,6 +13,8 @@ const PLAYER: int = 1 @export var log_path: String = "res://build/match/match.tclog" @export var stage: String = "lobby" +## H2: a GameSettings quality preset to draw with (-1: the view's defaults). +@export var quality: int = -1 var _replay: MatchReplay var _view: MatchView @@ -55,6 +57,11 @@ func _ready() -> void: _view = MatchView.new() _view.setup(sim, player_id) add_child(_view) + if quality >= 0: + var settings: GameSettings = GameSettings.new() + settings.quality = quality + settings.apply_to_viewport(get_viewport()) + _view.apply_settings(settings) var watched: int = _watched() var who: String = "nobody" if stage == "lobby" or stage == "tide": @@ -79,7 +86,7 @@ func _ready() -> void: else: _view.overview() _view.settle() - _caption(_describe(who)) + _caption(_describe(who) + ("" if quality < 0 else "\nquality: %s, renderer: %s" % [GameSettings.QUALITY_NAMES[quality], RenderingServer.get_current_rendering_method()])) func _player() -> SimEntity: diff --git a/test/capture/quality_high.tscn b/test/capture/quality_high.tscn new file mode 100644 index 0000000..8eaede5 --- /dev/null +++ b/test/capture/quality_high.tscn @@ -0,0 +1,8 @@ +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://test/capture/match_scene.gd" id="1"] + +[node name="CaptureQuality" type="Node3D"] +script = ExtResource("1") +stage = "landed" +quality = 2 diff --git a/test/capture/quality_low.tscn b/test/capture/quality_low.tscn new file mode 100644 index 0000000..4b74d6a --- /dev/null +++ b/test/capture/quality_low.tscn @@ -0,0 +1,8 @@ +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://test/capture/match_scene.gd" id="1"] + +[node name="CaptureQuality" type="Node3D"] +script = ExtResource("1") +stage = "landed" +quality = 0 diff --git a/test/capture/quality_medium.tscn b/test/capture/quality_medium.tscn new file mode 100644 index 0000000..2d8194c --- /dev/null +++ b/test/capture/quality_medium.tscn @@ -0,0 +1,8 @@ +[gd_scene load_steps=2 format=3] + +[ext_resource type="Script" path="res://test/capture/match_scene.gd" id="1"] + +[node name="CaptureQuality" type="Node3D"] +script = ExtResource("1") +stage = "landed" +quality = 1 diff --git a/test/client/test_game_settings.gd b/test/client/test_game_settings.gd index cbf6fd6..3171c8d 100644 --- a/test/client/test_game_settings.gd +++ b/test/client/test_game_settings.gd @@ -128,3 +128,64 @@ func _assert_defaults(loaded: GameSettings) -> void: assert_eq(loaded.mouse.mouse_sensitivity, fresh.mouse.mouse_sensitivity) for action: Dictionary in KeyBindings.ACTIONS: assert_eq(loaded.bindings.code_of(action["id"]), int(action["default"])) + + +func test_presets_rise_from_low_to_high() -> void: + var settings: GameSettings = GameSettings.new() + var previous: Dictionary = {} + for quality: int in GameSettings.QUALITY_NAMES.size(): + settings.quality = quality + var preset: Dictionary = GameSettings.QUALITY[quality] + assert_true([1, 2, 4].has(settings.shadow_splits()), "%s has 1, 2 or 4 shadow splits" % GameSettings.QUALITY_NAMES[quality]) + assert_true(preset["msaa"] == Viewport.MSAA_DISABLED or not preset["fxaa"], "no preset pays for both MSAA and FXAA") + if not previous.is_empty(): + assert_true(float(preset["shadow_distance"]) >= float(previous["shadow_distance"])) + assert_true(int(preset["shadow_splits"]) >= int(previous["shadow_splits"])) + assert_true(float(preset["render_scale"]) >= float(previous["render_scale"])) + previous = preset + settings.quality = GameSettings.QUALITY_HIGH + assert_eq(settings.shadow_splits(), 4) + + +func test_a_preset_sets_the_viewport_and_the_sun() -> void: + var viewport: SubViewport = SubViewport.new() + var settings: GameSettings = GameSettings.new() + settings.quality = GameSettings.QUALITY_LOW + settings.apply_to_viewport(viewport) + assert_near(viewport.scaling_3d_scale, 0.75, 0.001) + assert_eq(viewport.msaa_3d, Viewport.MSAA_DISABLED) + assert_eq(viewport.screen_space_aa, Viewport.SCREEN_SPACE_AA_FXAA) + settings.quality = GameSettings.QUALITY_HIGH + settings.apply_to_viewport(viewport) + assert_near(viewport.scaling_3d_scale, 1.0, 0.001) + assert_eq(viewport.msaa_3d, Viewport.MSAA_2X) + assert_eq(viewport.screen_space_aa, Viewport.SCREEN_SPACE_AA_DISABLED) + viewport.free() + var view: MatchView = MatchView.new() + view.sun = Look.sun() + view.add_child(view.sun) + settings.quality = GameSettings.QUALITY_MEDIUM + view.apply_settings(settings) + assert_true(view.sun.shadow_enabled) + assert_eq(view.sun.directional_shadow_mode, DirectionalLight3D.SHADOW_PARALLEL_2_SPLITS) + settings.quality = GameSettings.QUALITY_LOW + view.apply_settings(settings) + assert_false(view.sun.shadow_enabled, "low has no shadows") + view.free() + + +func test_presets_never_change_how_far_cover_is_drawn() -> void: + # A lower preset must never let a player see through trees and rocks it stopped + # drawing: nothing about props is in the presets. + for preset: Dictionary in GameSettings.QUALITY: + for key: String in preset: + assert_false(key.contains("range") or key.contains("detail") or (key.contains("distance") and key != "shadow_distance"), "preset key %s" % key) + + +func test_renderer_fallback_notice() -> void: + var none: PackedStringArray = PackedStringArray() + assert_eq(RendererCheck.notice_for("forward_plus", "forward_plus", none), "", "the renderer asked for") + assert_eq(RendererCheck.notice_for("forward_plus", "gl_compatibility", none), RendererCheck.NOTICE, "fell back to OpenGL") + assert_eq(RendererCheck.notice_for("forward_plus", "gl_compatibility", PackedStringArray(["--rendering-method", "gl_compatibility"])), "", "the player chose OpenGL") + assert_eq(RendererCheck.notice_for("forward_plus", "gl_compatibility", PackedStringArray(["--rendering-driver=opengl3"])), "", "the player chose OpenGL") + assert_eq(RendererCheck.fallback_notice(), "", "nothing to say headless") diff --git a/tools/capture.sh b/tools/capture.sh index 21787d8..68cea37 100755 --- a/tools/capture.sh +++ b/tools/capture.sh @@ -10,8 +10,10 @@ # # Environment: # CAPTURE_SIZE=1280x720 frame size -# CAPTURE_RENDERER=forward_plus Vulkan via Lavapipe (default, the shipping renderer), or -# compatibility for OpenGL via llvmpipe +# CAPTURE_RENDERER=forward_plus Vulkan via Lavapipe (default, the shipping renderer), +# compatibility for OpenGL via llvmpipe, or no_vulkan: +# asks for Vulkan with no Vulkan driver present, and +# expects the game to fall back to OpenGL (H2) # # Exits 0 when the PNG was written and isn't blank (pixel variance and colour count), # 1 when the render failed or came out blank, 2 on bad usage. Open the image and look @@ -49,10 +51,13 @@ fi size="${CAPTURE_SIZE:-1280x720}" [[ "$size" =~ ^[0-9]+x[0-9]+$ ]] || { echo "capture.sh: bad CAPTURE_SIZE '$size'" >&2; exit 2; } +env_args=() case "${CAPTURE_RENDERER:-forward_plus}" in - compatibility) render=(--rendering-method gl_compatibility --rendering-driver opengl3) ;; - forward_plus) render=(--rendering-method forward_plus --rendering-driver vulkan) ;; - *) echo "capture.sh: CAPTURE_RENDERER must be compatibility or forward_plus" >&2; exit 2 ;; + compatibility) render=(--rendering-method gl_compatibility --rendering-driver opengl3); wanted="gl_compatibility" ;; + forward_plus) render=(--rendering-method forward_plus --rendering-driver vulkan); wanted="forward_plus" ;; + # The project's own renderer (Forward+ on Vulkan), with no Vulkan driver to find. + no_vulkan) render=(); env_args=(-e VK_ICD_FILENAMES=/nonexistent/none.json -e VK_DRIVER_FILES=/nonexistent/none.json); wanted="gl_compatibility" ;; + *) echo "capture.sh: CAPTURE_RENDERER must be compatibility, forward_plus or no_vulkan" >&2; exit 2 ;; esac # Rebuild the image only when its recipe changes. @@ -84,9 +89,10 @@ output="$(timeout --signal=KILL 300 nice -n 15 docker run --rm --name "$name" \ --user "$(id -u):$(id -g)" \ --memory 3g --cpus 4 \ -e "CAPTURE_SCREEN=${size}x24" \ + "${env_args[@]}" \ -v "$repo:/repo" \ "$image" \ - "${render[@]}" --resolution "$size" \ + ${render[@]+"${render[@]}"} --resolution "$size" \ --script res://tools/capture.gd -- --scene="$scene" --out="res://$scratch" "${extra[@]}" 2>&1)" code=$? set -e @@ -102,10 +108,10 @@ if [[ -f "$repo/$scratch" ]]; then mv "$repo/$scratch" "$out" fi echo "$report" -# Godot silently falls back to OpenGL when Vulkan fails; that is not the requested capture. -wanted="${render[1]}" +# Godot falls back to OpenGL when Vulkan fails; unless that was the point, it is not the +# requested capture. if ! grep -q "\"renderer\":\"$wanted\"" <<<"$report"; then - echo "capture.sh: asked for the $wanted renderer, but Godot fell back to another" >&2 + echo "capture.sh: expected the $wanted renderer, but Godot used another" >&2 grep -iE 'vulkan|error' <<<"$output" | tail -n 10 >&2 || true exit 1 fi