Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 11 additions & 3 deletions docs/DISTRIBUTION.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,9 +35,15 @@ Windows/macOS export icons. The build-time editor remains omitted from the
vendored game dependency. No private engine source checkout, SDK source cache or
build tools are vendored.

Only a maintainer updating the dependency needs access to private engine
releases. Download all three SDK ZIPs and their adjacent `.zip.sha256` files from
one published release. Preserve the old addon outside the checkout, then run:
Future SDK updates come from the public `RakuenSoftware/wol-engine-release`
repository. Its controlled native CI temporarily reads private source and
publishes audited binaries only. The updater accepts exact `runtime-<commit>`
release URLs from that repository, while retaining the original engine's exact
runtime/resource release URLs for older SDKs. The vendored dependency above
remains unchanged until the first new SDK release is available.

Only a maintainer updating the dependency downloads the SDKs. Download all three
SDK ZIPs and their adjacent `.zip.sha256` files from one published release. Preserve the old addon outside the checkout, then run:

```sh
python tools/release.py --vendor-runtime /path/to/linux-sdk.zip \
Expand All @@ -46,6 +52,8 @@ python tools/release.py --vendor-runtime /path/to/linux-sdk.zip \

The updater checks archive/file hashes, matching commits and targets, compares
shared resources, rejects implementation source, and writes a new vendored tree.
New dependency updates reject loose shader programs as implementation source;
the current older SDK still contains four such files, pending replacement.
It refuses to overwrite an existing addon. Review and commit that directory and
VENDOR.json together. CI never runs this maintainer operation.

Expand Down
8 changes: 4 additions & 4 deletions docs/FIELD.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Geometry is a group count, a 64-byte header per group, and then each group's tri
- Retail space is x right, y down, z forward. A half turn about x gives the engine's y-up space; 128 map units are one engine unit.
- Polygons are back-face culled.
- Bit 0 of a polygon's command byte (byte 15) makes it double-sided: the room renderer draws a triangle that faces away rather than culling it (BATTLE.PRG 0x800973C8). It clears the bit before the GPU sees the polygon (0x8009756C, 0x800978DC), so every room polygon is modulated by its colours, never drawn raw.
- The room is drawn through an ordering table, so of two identical opaque faces facing the same way, the earlier group's is drawn over the later's. MAP005 (the chapel) has its floor's centre twice, in groups 102 (lit warm by the torches) and 103 (lit cold): only the warm one shows. The installer sets such a later copy half a unit behind its face, so it shows only where the earlier one is hidden.
- The room is drawn through an ordering table at each face's farthest corner (BATTLE.PRG 0x80097AB4; the fourth corner at 0x8009787C), in quarter-depth entries. Each emitted vertex keeps the primitive's four corners for the shared engine's ordering shader, including after the near-face filter rebuilds a mesh. This keeps an angled door from cutting through Ashley's leg. So of two identical opaque faces facing the same way, the earlier group's is drawn over the later's. MAP005 (the chapel) has its floor's centre twice, in groups 102 (lit warm by the torches) and 103 (lit cold): only the warm one shows. The installer sets such a later copy half a unit behind its face, so it shows only where the earlier one is hidden.
- Bits 13 and 14 of a group's flags are how many times its polygons near the camera are subdivided (less one for each 512 of depth).

**Room groups**
Expand Down Expand Up @@ -70,7 +70,7 @@ Geometry is a group count, a 64-byte header per group, and then each group's tri
- Past a depth (0x200 by default; `61` sets it, patching BATTLE.PRG 0x80097590 and 0x800978f8), the room renderer draws a polygon from the half-resolution copy of its texture: its texture coordinates halved and its page one row down. The game keeps those copies itself (the image-frame animations repeat each copy into them). The field's textures are mipmapped instead, so `61` changes nothing here.

**Near rejection**
- The retail room renderer drops each room polygon whose nearest corner depth, divided by four, is below the near clip (`eb`; 64 by default): 0x80097A10 takes the least of the three GTE depths and 0x800980F8 compares it, the near value patched into its code. A corner behind the camera has depth 0, so a polygon reaching behind the camera goes too. Only in first-person view (the switch at 0x800F19C8, the renderer's second argument) are near polygons first subdivided, by their group's levels (flags bits 13 and 14), and the pieces tested.
- The retail room renderer drops each room polygon whose farthest corner depth, divided by four, is below the near clip (`eb`; 64 by default): 0x80097A10 takes the greatest of the three GTE depths and 0x800980F8 compares it, the near value patched into its code. A corner behind the camera has depth 0. A face is rejected by that test only when its farthest corner is below the cut. Only in first-person view (the switch at 0x800F19C8, the renderer's second argument) are near polygons first subdivided, by their group's levels (flags bits 13 and 14), and the pieces tested.
- So room geometry closer than four times the near clip is not drawn, and a camera beside a wall or prop sees past it.
- `ec v` sets a view scale of v × 128 (4096 for 0; 0x800BDE58), which 0x8007CD14 stores at 0x1F800064 and 0x8007AF08 multiplies into the whole view matrix, translation included. That leaves every screen position as it is but scales every depth, so the near cut stands at four times the near clip over v / 32: under MAP003's `ec 128` close-up by the cart it is 64 units, and the cart's cover, some 160 units from the eye, is drawn in front of Ashley.
- The GPU then skips any triangle more than 1023 pixels across or 511 down (a quad reaches it as two triangles, each tested alone). Room corners are projected as the GTE projects a character's (see **Near the camera** below): a corner nearer than H / 2 after the view's scale, or behind the eye, is placed as if it stood there, and its screen place is held within -1024 to 1023. None of the renderer's own tests (0x80098014's off-screen checks, the near cut, the cut again after the group's depth bias, the upper half of its header word) drops MAP172's door in the shot over Ashley's shoulder (Episode 1, 16:53, `ea 46`, `eb 01`, `ec 80`): ajar by -300 and 12 to 60 units from the eye, its upper half spans about 1050 pixels across and 670 down, so the GPU skips it and the man on the table shows. In the shot of the woman at that door (16:55) it is drawn, ajar as group script 0x40 stands it.
Expand Down Expand Up @@ -123,12 +123,12 @@ projection, and the body's own pose stays independent.

`installation/CharacterConversion.cs` turns an SHP model and its SEQ animation sets into a skinned glTF rig. `RetailContent.Rig` builds it when the field first spawns the character, and `FieldScene.PrepareRigBank` and `ActivateRig` attach it to an actor.

- **Props.** A model with no animations of its own (the opening's dead men, 0x73 to 0x76) gets one clip, `rest`, which the field plays in place of the base idle. Its root stands half its bone 1 length above the actor's place, as the actor renderer lifts every model (BATTLE.PRG 0x800AF620 adds half the model's word at +0x50, bone 1's length, to the drawn height), and its bone 1 takes the standing turn every humanoid animation set gives the hip as its base, (2048, 0, 6144) in 8192ths of a turn. The props are modelled as they lie in their scenes, so unturned they stood on end: Episode 1 at 16:50 (MAP172) has the man slumped in the chair and the man spread on his back across the sloping table, which the script's angles (33) tilt him to fit. The man slumped in MAP172's chair (0x73) is a measured exception: retail draws him against the chair's back, 54 units from the place his script gives him (53 ahead and 11 to one side in his own frame), so his `rest` root carries that offset. It was fitted by rendering him over a grid of places and scoring each against Episode 1 at 16:51 (from beside the chair) and 16:54 (over Ashley's shoulder); the same fit leaves the man on the table (0x74) where his script puts him, and a different turn or tilt about his place fits worse. How retail comes by the offset was not found: the draw routine (0x800B1A68) gives bones 0 and 1 the actor's own matrix, built from its place and angles, and nothing read there moves him.
- **Props.** Loose models with a zero centre (including the opening’s swords and bolts) keep neutral root and hip bones. An animated prop holds its last pose when its event clip ends, as do characters; glTF loop flags are restored from the decoder’s explicit clip list. Static humanoid props with a nonzero centre (the opening's dead men, 0x73 to 0x76) gets one clip, `rest`, which the field plays in place of the base idle. Its root stands half its bone 1 length above the actor's place, as the actor renderer lifts every model (BATTLE.PRG 0x800AF620 adds half the model's word at +0x50, bone 1's length, to the drawn height), and its bone 1 takes the standing turn every humanoid animation set gives the hip as its base, (2048, 0, 6144) in 8192ths of a turn. The props are modelled as they lie in their scenes, so unturned they stood on end: Episode 1 at 16:50 (MAP172) has the man slumped in the chair and the man spread on his back across the sloping table, which the script's angles (33) tilt him to fit. The man slumped in MAP172's chair (0x73) is a measured exception: retail draws him against the chair's back, 54 units from the place his script gives him (53 ahead and 11 to one side in his own frame), so his `rest` root carries that offset. It was fitted by rendering him over a grid of places and scoring each against Episode 1 at 16:51 (from beside the chair) and 16:54 (over Ashley's shoulder); the same fit leaves the man on the table (0x74) where his script puts him, and a different turn or tilt about his place fits worse. How retail comes by the offset was not found: the draw routine (0x800B1A68) gives bones 0 and 1 the actor's own matrix, built from its place and angles, and nothing read there moves him.

- **Enhanced 2D art and text** (the engine's graphics panel: Enhanced 2D art, on at 2x, and Enhanced text, on at 4x, each 2x, 4x or 8x). What is drawn on the 320 by 240 screen, the HUD, the menus, the balloons' paper, overlays and the ending's pictures, comes from `RetailContent.ScreenTexture`, enlarged at load by the engine's `PixelArtScaler` (Scale2x for art, which keeps the palette; anti-aliased for the HUD's lettering) while it reports its original size, so every region drawn of it is placed as before. The bitmap fonts load through the engine's `BitmapFontAsset` at the text factor, their glyph metrics unchanged. A change of either setting remakes the kept pictures and fonts in place. The title draws into fixed-size viewports of the retail screen and the field's 3D textures (rooms, characters, effects) are not affected.
- **Enhanced characters** (`runtime/CharacterQuality.cs`, Settings › Characters, a saved preference; Original by default, which every footage comparison uses). Made at runtime from the installed rigs, nothing stored:
- textures are scaled up four times: doubled twice by an edge-following pixel-art scaler (a quarter takes a neighbour's colour where that neighbour and the next one round agree across the corner and the opposite pair differ; colours alike within 48 in brightness, 7 and 6 in the colour differences; transparent texels only match each other), then each texel blended with its alike neighbours (5 by 5, one pass, within 12 in brightness, so low-contrast folds such as a hood's keep their lines) and sharpened a little against that blend; drawn with mipmaps and smooth, anisotropic filtering;
- a head that is one shell (the one-sided faces wholly on the head bone, the bone whose part byte is 1: at least 20 edges, at most one in 40 shared by more than two faces, at most three tenths open) is divided twice; a layered head (a hood over a face, as MAP003's hooded soldier, or a helmet) is not, as lifting its outer layer pushes it through the inner one. Its faces are each new edge point lifted onto the curved-triangle edge between its corners' averaged normals; border edges stay straight, so the head meets neck and hair where it did;
- a head that is one shell (the one-sided faces wholly on the head bone, the bone whose part byte is 1: at least 20 edges, at most one in 40 shared by more than two faces, at most three tenths open) is divided twice; a layered head (a hood over a face, as MAP003's hooded soldier, or a helmet) is not, as lifting its outer layer pushes it through the inner one. Its faces are each new edge point lifted onto the curved-triangle edge between its corners' averaged normals; border edges stay straight, so the head meets neck and hair where it did. Vertex colours and alpha are interpolated along each divided edge too, preserving the original shading;
- smooth normals (per bone, corners at one place shared) and per-pixel shading: a light from above, to the camera's left and in front, that turns with the camera (0.7, wrapped Lambert, no highlights), and an even fill (0.55). Rooms and effects are unshaded, so only characters take it; the room's light map still tints them as before. The item menu's Ashley stays unshaded.
The render scale (up to 200 %) and antialiasing in the shared graphics panel supersample their outlines further.
- **Enhanced lighting** (`runtime/FieldLighting.cs`, Settings › Lighting, a saved preference; Original by default). Bright things bloom (glow over 0.9 of white, levels 2 to 5, added); effects' added sprites (fire, magic) are drawn three times brighter, which blooms and on an HDR display shows brighter than white; and each effect casts a light from its added sprites' middle, coloured by their texels and tints, its strength following how much of them there is, so firelight flickers on the characters near it (when they are drawn enhanced and take light).
Expand Down
Loading
Loading