metaheavens/spaceship
Watch
1
0
Fork
You've already forked spaceship
 0
Code Issues 4 Pull requests Projects 1 Releases Packages Wiki Activity

Make the lunar backdrop cheap: 3x3 field, then bake and tile it (#68)

Browse source 
The crater shader ran on every pixel of a fullscreen rect every frame and
was by far the most expensive thing in the surface scene. Nothing else came
close: RockField keeps 14 rocks alive, Rock/Ship/Enemy already avoid
per-frame queue_redraw() for transform-only changes, and LunarBackground.gd
is a handful of scalar ops.

Three reductions to the field itself:

- 5x5 -> 3x3 neighbour scan. That width was never the geometric answer;
  it was insurance against craters seen clipping at cell boundaries
  on-device, i.e. a crater reaching past its nominal radius because a hash
  returned a value outside [0,1] and extrapolated mix(). Clamping the
  crater CENTRE into its own cell, alongside the radius clamp already
  there, bounds the reach whatever the hash returns - so a crater two cells
  out is >= 1.0 cells away, a normalized distance of >= 2.63, past every
  threshold the shading reacts to (the last saturates at 1.15). The outer
  ring provably cannot change a pixel. This removes the clipping bug's
  cause instead of hiding it behind 16 extra samples.
- One hash42 per cell instead of hash21 twice plus hash22, decorrelating
  on output lanes rather than input offsets.
- Squared distances in the loop, square-rooted twice at the end rather
  than once per sample.

Measured with the new tests/profile_shader.sh, above softpipe's own ~657ms
fullscreen floor: 9482ms -> 405ms of shader work, a 23x reduction.

Then the larger change: the field is a fixed function of world position, so
every frame recomputed an identical answer. It is now made periodic (the
cell index is wrapped before hashing, which makes a Worley field tile
exactly rather than merely blend), baked once at load into one tile, and
scrolled with repeat wrapping by lunar_tiled.gdshader - one texture fetch
per pixel. Two honest costs: the field repeats every 7040 world units, and
a fixed-resolution tile softens when zoomed past 1:1. Lunar regolith is
forgiving of both, having no landmarks and being smooth gradients already.

The bake waits a frame and asks the material whether it actually samples a
field_texture, so a gas giant - which swaps in its own background shader
(#51) - does not pay for a 2048-square tile it will never read. Headless
runs skip it entirely, having nothing to rasterize.

tests/test_lunar_field.gd guards the reasoning, since a fragment shader
cannot be asserted on directly: the premises are still in the source, the
worst-case ring-2 geometry stays clear of every threshold independent of
the hash, a 3x3 and a 5x5 scan render identically over 4000 sampled points,
the field repeats exactly in both axes, and the miss sentinel still cannot
overflow mediump into +Inf and then NaN.

test_surface_profiles.gd asserted "a rocky landing leaves the background
alone" by naming lunar_surface.gdshader; it now reads the shader from the
scene, which is the property it actually cares about.

PlanetSurface.tscn's edit also carries the planet-name relocation described
in the HUD commit - same scene file, so the two cannot be split.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Loïc Wisniewski 2026-08-17 23:20:14 +02:00
commit 657ca9d035
11 changed files with 845 additions and 74 deletions
Download patch file Download diff file Expand all files Collapse all files

198
lunar_surface.gdshader
View file

@ -25,6 +25,14 @@ shader_type canvas_item;
// a thin bright rim wedge through the middle of the merged basin. The
// second-nearest distance is tracked purely to detect that case and fade
// the rim out there - see the note further down.
//
// This runs on EVERY pixel of a fullscreen rect on a phone, so it is the
// single most expensive thing in the surface scene and the subject of
// Forgejo #68 ("the moon game is a bit slow"). The three optimizations
// that brought it down - a bounded 3x3 scan, one hash per cell instead of
// three, and one sqrt per pixel instead of one per sample - are each
// justified at the point they appear below. Time it with
// bash tests/profile_shader.sh res://lunar_surface.gdshader
uniform vec2 camera_cell = vec2(0.0, 0.0);
uniform vec2 camera_frac = vec2(0.0, 0.0);
@ -46,33 +54,62 @@ uniform vec4 highlight_color : source_color = vec4(0.89, 0.89, 0.90, 1.0);
// cuts appear in this grayscale output the FIELD is at fault, and if
// it is smooth the field is fine and the SHADING is at fault.
uniform float debug_mode = 0.0;
// Width of the repeating tile, in cells. The crater field is made PERIODIC
// with this period (see the wrap in the loop), which is what lets
// LunarBackground.gd bake one square of it into a texture and then scroll
// that texture forever with repeat wrapping, instead of re-deriving the
// field per pixel per frame. Set from LunarBackground.TILE_CELLS, which is
// the single source of truth shared with lunar_tiled.gdshader.
uniform float tile_cells = 32.0;
// BAKE MODE. 0 = normal camera-relative sampling for direct display.
// Above zero, UV is mapped straight onto [0, tile_cells] instead, so
// rendering this shader to a square SubViewport produces exactly one period
// of the field - the texture the runtime shader then samples.
uniform float bake_cells = 0.0;
const vec2 LIGHT_DIR = vec2(-0.6, -0.8);
const float MIN_RADIUS = 0.16;
// MUST stay below 1.0. The 3x3 scan below is only correct because a crater
// cannot reach out of its own cell's immediate neighbourhood; see the long
// note at the loop. tests/test_lunar_field.gd asserts this bound directly
// against the shader source so it cannot drift unnoticed.
const float MAX_RADIUS = 0.38;
// Sentinel for "this cell holds no crater". Must stay well inside mediump
// range (max ~65504) so it can never become +Inf - see the note in the
// loop. Only needs to exceed the largest real normalized distance (~18).
const float MISS_DISTANCE = 1000.0;
// Sentinel for "this cell holds no crater", in SQUARED normalized units to
// match the loop. Must stay well inside mediump range (max ~65504) so it
// can never become +Inf - see the note in the loop. Only needs to exceed
// the largest real squared normalized distance, which for a 3x3 scan is
// (2.83 cells / 0.16 min radius)^2 ~= 313.
const float MISS_DISTANCE_SQ = 10000.0;
// Loop-carried initial value. Above any real value INCLUDING one carrying
// the miss sentinel (~10313), so a pixel whose whole neighbourhood is
// empty still leaves the "winning" offset populated with something finite.
const float START_DISTANCE_SQ = 20000.0;
// One hash call yields all four values a cell needs (crater centre x/y,
// whether the cell holds a crater at all, and its radius). The previous
// version called two different hashes three times per cell with different
// constant offsets, which was three quarters of the loop body's arithmetic
// for no extra information - a single hash with four independent output
// lanes decorrelates just as well.
//
// Multipliers chosen for precision safety on mobile GPUs: they are all
// < 1, so every intermediate stays small no matter how large the cell
// index gets. An earlier version multiplied by ~123/456 first, which lands
// the intermediate in the thousands where a mobile float loses its
// fractional bits entirely. (Standard "hash without sine" formulation,
// Dave Hoskins.)
vec4 hash42(vec2 p) {
vec4 p4 = fract(vec4(p.xyxy) * vec4(0.1031, 0.1030, 0.0973, 0.1099));
p4 += dot(p4, p4.wzxy + 33.33);
return fract((p4.xxyz + p4.yzzw) * p4.zywx);
}
// Hash pair chosen for precision safety on mobile GPUs. The previous
// version multiplied the cell coordinate by ~123/456 before fract(), which
// lands the intermediate in the thousands where a mobile float loses its
// fractional bits entirely. These multipliers are all < 1, so every
// intermediate stays small no matter how large the cell index gets.
// (Standard "hash without sine" formulation, Dave Hoskins.)
float hash21(vec2 p) {
vec3 p3 = fract(vec3(p.xyx) * 0.1031);
p3 += dot(p3, p3.yzx + 33.33);
return fract((p3.x + p3.y) * p3.z);
}
vec2 hash22(vec2 p) {
vec3 p3 = fract(vec3(p.xyx) * vec3(0.1031, 0.1030, 0.0973));
p3 += dot(p3, p3.yzx + 33.33);
return fract((p3.xx + p3.yz) * p3.zy);
}
void fragment() {
vec2 screen_px = UV * viewport_size;
vec2 centered = screen_px - viewport_size * 0.5;
@ -92,11 +129,18 @@ void fragment() {
// calling floor(x) and fract(x) separately lets the GPU round the two
// evaluations differently, which right at a cell boundary makes them
// disagree by a full cell and snaps the sampled point one cell sideways.
vec2 rel = camera_frac + centered * (camera_zoom / cell_size);
//
// In bake mode none of that applies: the target is one tile of the field
// in isolation, so UV maps directly onto [0, bake_cells] and there is no
// camera in the picture at all.
bool baking = bake_cells > 0.0;
vec2 rel = baking
? UV * bake_cells
: camera_frac + centered * (camera_zoom / cell_size);
vec2 cell_rel = floor(rel);
vec2 local = rel - cell_rel;
// Absolute cell index, used only for hashing. Built from exact integers.
vec2 cell = camera_cell + cell_rel;
vec2 cell = baking ? cell_rel : camera_cell + cell_rel;
// Single scalar field: normalized distance to the nearest crater.
// < 1.0 means this pixel is inside that crater; 1.0 is exactly on its
@ -110,22 +154,49 @@ void fragment() {
// through the middle of what should read as one merged depression.
// A pixel in that region is inside BOTH craters, i.e. second_nearest is
// also < 1.0 - which is precisely the condition to fade the rim out.
float nearest = MISS_DISTANCE;
float second_nearest = MISS_DISTANCE;
vec2 nearest_dir = vec2(0.0, 1.0);
//
// Tracked SQUARED, and square-rooted once at the end. Ordering is
// unchanged by squaring (both sides are non-negative), so the same
// crater wins - but this turns one sqrt per sample into two per pixel,
// and sqrt is one of the more expensive things a fragment shader can
// ask for.
float nearest_sq = START_DISTANCE_SQ;
float second_nearest_sq = START_DISTANCE_SQ;
vec2 nearest_offset = vec2(0.0, 1.0);
// 5x5 rather than 3x3. A crater's radius is at most MAX_RADIUS cells,
// so in theory 3x3 covers every crater that could possibly reach this
// pixel - but on-device, craters were still being clipped exactly at
// cell boundaries, which means some crater's influence was reaching
// further than the scan did (e.g. a hash returning a value outside its
// nominal range on that GPU, inflating a radius). Scanning two cells
// out costs more samples but makes the clip impossible to reach even
// if a radius comes out several times larger than intended.
for (int dx = -2; dx <= 2; dx++) {
for (int dy = -2; dy <= 2; dy++) {
// 3x3 is provably sufficient, and provably so only because of the two
// clamps in the loop body. A crater's centre is clamped into its own
// cell and its radius is clamped to at most MAX_RADIUS (0.38) cells, so
// the furthest a crater can reach past its own cell is 0.38 cells. This
// pixel's `local` lies in [0,1], so a crater two cells out is at least
// 1.0 cells away - a normalized distance of at least 1/0.38 = 2.6,
// which is past every threshold used below (the floor fades out by 0.9,
// the rim band by 1.0, and the overlap suppression saturates at 1.15).
// Such a crater therefore cannot change a single pixel of the output.
//
// This replaces an earlier 5x5 scan. That width was not chosen from the
// geometry - 3x3 was already the geometric answer - but as insurance
// against craters that were observed clipping at cell boundaries
// on-device, which meant some crater's influence was reaching further
// than its nominal radius allowed, e.g. a hash returning a value outside
// [0,1] on that GPU and extrapolating mix() into a huge radius. Clamping
// both the radius AND the centre fixes that at the source and makes the
// bound above hold no matter what the hash returns, so paying for 25
// samples per pixel to hide a driver quirk is no longer necessary.
// tests/test_lunar_field.gd checks the two scans agree exactly.
for (int dx = -1; dx <= 1; dx++) {
for (int dy = -1; dy <= 1; dy++) {
vec2 offset = vec2(float(dx), float(dy));
highp vec2 neighbor_cell = cell + offset;
// Wrapping the cell index before hashing is the entire trick that
// makes the field tileable: cell N and cell N + tile_cells hash
// identically, so the pattern repeats exactly with that period.
// It works on a Worley field specifically because the scan only
// ever reads immediate neighbours - wrap those consistently and
// the seam is not merely hidden, it does not exist. GLSL mod()
// returns a non-negative result for a positive divisor, so
// negative cell indices wrap correctly too.
highp vec2 neighbor_cell = mod(cell + offset, tile_cells);
vec4 h = hash42(neighbor_cell);
// Cells without a crater are pushed far away rather than
// branched around, keeping the loop body uniform. NOTE the
@ -134,32 +205,45 @@ void fragment() {
// becomes +Inf there, and (1.0 - has_crater) * Inf evaluates to
// 0 * Inf = NaN for every cell that DOES hold a crater - which
// compares false against everything and would silently discard
// every crater. MISS_DISTANCE only has to beat the largest real
// normalized distance (~2.9 cells / 0.16 min radius ~= 18).
float has_crater = step(0.35, hash21(neighbor_cell + vec2(41.0, 5.0)));
vec2 crater_center = offset + hash22(neighbor_cell);
// every crater.
float has_crater = step(0.35, h.z);
// clamp() on both of these is what bounds a crater's reach to
// its own cell plus MAX_RADIUS, which is what lets the scan
// above be 3x3. Without them a driver returning a hash outside
// [0,1] could place a centre, or inflate a radius, far enough to
// reach past the scan - which is exactly the clipping that was
// seen on-device.
vec2 crater_center = offset + clamp(h.xy, 0.0, 1.0);
float radius = clamp(mix(MIN_RADIUS, MAX_RADIUS, h.w), MIN_RADIUS, MAX_RADIUS);
vec2 to_sample = local - crater_center;
float dist = length(to_sample);
// clamp() guards against a hash landing outside [0,1] on some
// driver and extrapolating mix() into a huge radius.
float radius = clamp(mix(MIN_RADIUS, MAX_RADIUS, hash21(neighbor_cell + vec2(9.0, 2.0))), MIN_RADIUS, MAX_RADIUS);
float normalized_sq = dot(to_sample, to_sample) / (radius * radius)
+ (1.0 - has_crater) * MISS_DISTANCE_SQ;
float normalized = dist / radius + (1.0 - has_crater) * MISS_DISTANCE;
if (normalized < nearest) {
second_nearest = nearest;
nearest = normalized;
// Direction from the winning crater's centre to this pixel,
// used for the rim's light/shadow split. Taken from the SAME
// crater that won the distance test, so the shading can never
// describe one crater while the floor describes another.
nearest_dir = dist > 0.0001 ? to_sample / dist : vec2(0.0, 1.0);
} else if (normalized < second_nearest) {
second_nearest = normalized;
if (normalized_sq < nearest_sq) {
second_nearest_sq = nearest_sq;
nearest_sq = normalized_sq;
// Offset from the winning crater's centre to this pixel,
// kept so the rim's light/shadow split can be derived from
// the SAME crater that won the distance test - the shading
// can then never describe one crater while the floor
// describes another.
nearest_offset = to_sample;
} else if (normalized_sq < second_nearest_sq) {
second_nearest_sq = normalized_sq;
}
}
}
float nearest = sqrt(nearest_sq);
float second_nearest = sqrt(second_nearest_sq);
// normalize() would divide by zero for a pixel sitting exactly on a
// crater centre; the guard keeps that pixel's rim term merely arbitrary
// rather than NaN. It is deep inside the floor, where the rim band is
// zero anyway.
float offset_length = length(nearest_offset);
vec2 nearest_dir = offset_length > 0.0001 ? nearest_offset / offset_length : vec2(0.0, 1.0);
vec2 light_dir = normalize(LIGHT_DIR);
float facing = dot(nearest_dir, light_dir);
@ -188,8 +272,14 @@ void fragment() {
// can visibly "step" into faint bands on real hardware. A small random
// jitter well under one visible step breaks the stepping up without
// being perceptible as noise.
float dither = (hash21(screen_px + vec2(7.0, 13.0)) - 0.5) / 128.0;
color += vec3(dither);
// Skipped when baking: dither is a per-SCREEN-pixel jitter, and baking it
// would freeze the noise into the texture, where magnification smears it
// into visible blotches and tiling repeats it. lunar_tiled.gdshader
// applies the identical term live instead, which is where it belongs.
if (!baking) {
float dither = (hash21(screen_px + vec2(7.0, 13.0)) - 0.5) / 128.0;
color += vec3(dither);
}
// Diagnostic checkerboard: alternate cells tinted, plus a bright line
// right at each cell edge. Makes the grid unmistakable in a screenshot.