H2: Graphics presets, OpenGL fallback notice, tested configurations

Presets now tune shadows, cascades, render scale and anti-aliasing:
Low (no shadows, 75%, FXAA), Medium (200 m, 2 cascades, FXAA), High
(400 m, 4 cascades, MSAA 2x). GameSettings.apply_to_viewport sets the
viewport; MatchView.apply_settings sets the sun's cascades. No preset
changes how far props or pieces are drawn, so a lower one never shows a
player through cover; a test guards it.

When Vulkan can't start, Godot falls back to OpenGL (fallback_to_opengl3)
and RendererCheck has the main menu say so. tools/capture.sh gains
CAPTURE_RENDERER=no_vulkan, which hides the Vulkan driver and expects the
fallback. New scenarios quality_low/medium/high draw a match moment with
each preset, reviewed in both renderers.

docs/PLAY.md lists the presets, renderers, Wayland and hybrid-GPU notes,
and the tested configurations, marking each as software-rendered only or
not tested.

Closes #55

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-14 00:11:13 -05:00
co-authored by Claude Opus 5.5
parent 4439d9a84f
commit 54c255e912
14 changed files with 254 additions and 18 deletions
+4 -1
View File
@@ -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.
+71
View File
@@ -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
+2
View File
@@ -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()
+28
View File
@@ -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
+1
View File
@@ -0,0 +1 @@
uid://duaotpjllo5rf
+27 -7
View File
@@ -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
+2
View File
@@ -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
+11
View File
@@ -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"))
+8 -1
View File
@@ -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:
+8
View File
@@ -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
+8
View File
@@ -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
+8
View File
@@ -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
+61
View File
@@ -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")
+15 -9
View File
@@ -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