Epok Engine
Documentation/Render & animate

Fog, water and texture animation

START WITH THE BIG PICTURE

What does this part of Epok do?

Fog, scrolling UVs and screen fades add motion and depth without a modern shader stack. They are small tools that can make a compact scene feel much larger.

  1. 01Set environment fog
  2. 02Animate selected material UVs
  3. 03Use screen fade directly or in transitions

What is happening under the hood?

  • Depth fog blends supported geometry toward a scene color.
  • UV scroll uses authored speed and measured runtime time.
  • Screen fade is a resident runtime value shared with scene transitions.

Field note: Fog is seasoning, not soup. Start subtle, then test on the actual output resolution.

The Lighting window contains Distance Fog with enabled, start/end distance and tint controls. Fog linearly depth-cues world mesh vertex colors and sprite tint between the two distances. Distances use camera-space world units, with a maximum far distance of 128. This is PSX vertex color modulation before texture sampling; black texels remain black even at full fog. It is a bounded atmosphere effect, not a full-screen postprocess. HUD elements remain unaffected. Scene transitions restore each scene's fog settings. The same settings are authorable from C++, Blueprint and every Lua execution mode through the Scene group: scene.fog() returns the current FogSettings record and scene.set_fog(value) applies one. Tint channels are clamped to 8-bit values. A range outside 0 ≤ start_distance < end_distance ≤ 128, or narrower than one Q12 step, is rejected whole: set_fog returns false and mutates nothing, so a scripted scene accepts exactly what the editor validator accepts. The distances are spelled start_distance and end_distance because end is a Lua keyword.

Texture materials expose UV scroll / second, in normalized texture cycles per second per axis, from −4 to +4. Runtime uses the stable simulation clock, so pause stops scrolling. At texture-wrap boundaries, the renderer splits each triangle before converting UVs to page pixels; an entire 0–1 tile continues to cover the surface instead of collapsing when its endpoints wrap. Colors and positions interpolate across the split and the resulting triangles use the existing near/far clipping and ordering table. Split triangles consume the scene triangle budget; dropped primitives remain observable in renderer counters. The editor uses the same seam subdivision for preview.

A reusable water surface is an ordinary thin mesh with a blue imported texture, Average or Add blending, and a small UV scroll such as (0.12,0.04). It needs no game-specific water component or rigid-body simulation. The demo project's Water mesh includes scrolling, semitransparency and a palette animator. Its Night scene enables distance fog.

The Palette Animator component cycles a selected imported texture's quantized palette entries. It affects all uses of that texture, including world meshes, sprites and HUD images. Configure the first/last visible color indices, step rate and reverse direction; index zero remains transparent. One enabled animator owns each texture's palette. Disabling the component or replacing a scene restores the base colors. Palette uploads are bounded and synchronized with GPU work.

Runtime helpers are available to Behaviours through entity().palette_animator; epok::fog_environment is fog's Q12 backing store, read by scene.fog and written by scene.set_fog rather than reached directly, and mesh scroll rates are the Q12 material.uv_scroll[2] fields. Simulation owns progression; game code owns transitions and direction changes. Host tests verify wrapped UV coverage and fog interpolation, while the demo exercises all effects in the exported PSX build.

Screen fade

The fade is authorable from C++, Blueprint and every Lua execution mode through the Scene group: scene.screen_fade() returns the current amount, from 0 (clear) to 255 (opaque black), and scene.set_screen_fade(value) applies one, clamping anything above 255 rather than rejecting it. epok::screen_fade is the 8-bit backing store, read and written by those two rather than reached directly. The getter reports the authored amount; what is drawn is the larger of it and a running scene transition's opacity, which scene.transition_snapshot() reports, so the fade and a transition share one pass without either hiding the other's value. The native renderer applies a subtractive full-screen rectangle after the world and HUD, using fixed double-buffered packets; 255 uses opaque black to guarantee complete coverage. At zero no overlay is submitted. The pass restores normal average blending afterward and does not invalidate the HUD cache or change scene materials. Intermediate intensities follow PSX color precision and subtractive blending, rather than a modern alpha-compositing curve.

The value deliberately survives scene-bank activation. A game can animate it using fixed simulation time, render black before request_scene(), and fade back from black in the incoming scene. The game owns timing and resetting the value to zero. No editor-authored fade track is required. A music fade can run alongside it by interpolating AudioSource.volume; wait for XA playback to start before advancing the envelope when synchronization is needed.

Sky gradient background

A camera's Background (Inspector > Camera) is either a Flat sky color, the default and the historic behavior, or a Sky gradient: the sky color overhead, a Horizon color along the horizon, and a Ground color below it. The Inspector shows a swatch of the three. Wherever no geometry covers the screen, the camera then shows ground below the horizon and sky above it, so gaps and pits in a level read as dark ground instead of sky. The sky color is reached about 45 degrees above the horizon and the ground color about 15 degrees below it.

The runtime splits the screen along the true horizon, for any pitch or roll, and draws each side as at most three dithered Gouraud triangles in place of the flat clear. The corner colors come from the elevation of the view ray through each corner, computed once per frame in 32-bit fixed point. The Scene view and the Game view draw the same gradient per pixel. On a study scene the pit floors that showed sky now show the ground color, and the average frame rate along a 90-second guided camera path was unchanged (56.18 fps with and without the gradient, in the embedded emulator).

The setting is stored as camera_sky_gradient (horizon and ground RGB, 0 to 1) on the camera; it is absent for a flat sky.

Documentation for v0.10.0 · View technical source · 6d01853