Posts on ~

Ultima Underworld PSX outside a PlayStation: AbyssX

rogerswaggoner@gmail.com (Roger Waggoner) — Thu, 18 Jun 2026 00:00:00 -0400

I’ve been working on AbyssX, a C++20 reimplementation of the PlayStation version of Ultima Underworld.

It is still incomplete, but it has reached a fun point: I can wander around the first level, interact with objects, manage inventory, and get into fights.

What is working

The video is mostly me poking around level one, but a lot has to be in place before that is possible:

the original BIN/CUE game data is read locally
DATA/AVATAR resources are loaded through the native storage layer
map and object state are far enough along for first-level exploration
inventory handling works
combat works
world object interaction works
input and VSync-style timing are connected to the recovered game loop
rendering is far enough along to make the level playable
native audio, video, and platform backends cover enough of the PSX-facing contracts for early gameplay

There is a useful modding path now, too.

At startup, AbyssX can build a virtual DATA/AVATAR archive from local override files. That lets me experiment with resource changes without patching the original disc image. I used that to adapt an existing English patch into a native text override.

What is not working yet

Plenty.

AddressSanitizer is especially noisy right now. Some crashes are ordinary reimplementation bugs. Others come from recovered original out of bounds indexing, buffer overflows, etc.,

Still, it is a good milestone. Enough of the recovered game is running through native systems that the result feels like a game again. It’s like seeing light at the end of a very, very long tunnel.

What’s next

The next phase is mostly correctness work:

work through AddressSanitizer crashes, including unsafe assumptions inherited from the original game code
improve rendering and audio edge cases
expose local save storage cleanly
keep filling in map, object, script, and resource semantics
compare more behavior against the original PlayStation executable

Reverse Engineering DOS Games on FM Towns

rogerswaggoner@gmail.com (Roger Waggoner) — Thu, 04 Dec 2025 12:48:14 -0500

I’ve been reverse engineering old DOS games, and one of the biggest headaches is segmented memory. Real-mode x86 is painful to work with in Ghidra - even if the tooling wasn’t lacking, dealing with segmented memory is still difficult.

So I’ve been looking for ports that avoid it. Enter the FM Towns.

Why FM Towns?

The FM Towns is a bit of an oddity. It’s x86-based, but it’s not IBM PC compatible - it ran its own custom version of MS-DOS and won’t work with DOSBox. What makes it interesting for RE is that applications used a DOS extender by default, giving you flat 32-bit protected mode binaries instead of segmented real-mode nightmares.

The FM Towns was popular in Japan, and many Western games got Japanese ports. If a game you’re interested in has a Towns version, there’s a good chance you can work with a flat memory model instead.

From what I’ve seen, most of these applications use the Phar Lap DOS extender. I’ve written a Ghidra loader for the P3 format (the most common one I’ve encountered) - I’ll get that on GitHub eventually.

Adding tracing to Tsugaru

Static analysis only gets you so far. I wanted to record execution traces, so I forked Tsugaru (the main FM Towns emulator) to add tracing support.

Traces are stored in SQLite for easy querying. The tracer runs on a separate thread, so runtime overhead is minimal.

STARTTRACE output.db -SNAPINT 0 -PCRANGE 0x400000 0x450ee3 -ADAPTIVE 1000

The flags:

-PCRANGE: Only trace instructions within this address range. This is in linear address space so you’ll need to figure out the mappings.
-SNAPINT 0: Snapshot interval - 0 disables periodic memory snapshots, otherwise it’s in # of instructions.
-ADAPTIVE 1000: Throttle capture after 1000 hits to the same address

This captures memory reads/writes, CALLs, and RETs for instructions in the specified range.

Keeping trace sizes manageable

Naive tracing would generate gigabytes in minutes. The tracer deduplicates aggressively and uses adaptive throttling to back off from hotspots. Playing Ultima Underworld for 30 minutes produced about 214MiB of trace data, with growth slowing significantly after the first ~150MiB as the throttling kicks in.

What’s next

I’ll cover how I’m using these traces to map out Ultima Underworld’s internals in a future post. The Ghidra loader and the Tsugaru fork will be on my GitHub once they’re cleaned up.

Infinity FM-Towns Driver

rogerswaggoner@gmail.com (Roger Waggoner) — Thu, 27 Nov 2025 00:31:09 -0500

INFINITY Co.,Ltd., a studio that ported games to the FMTowns system, used a small FMTowns graphics wrapper to assist with this.

I’m actually not sure if this is something that was written by INFINITY or was provided in an SDK for FMTowns, but I did find it with one of their ports.

The file has no standard header and begins with a 26-entry long jump table:

 |_ram:00000000 [0] addr drv_InitWithReloc
 |_ram:00000004 [1] addr drv_ShutDown
 |_ram:00000008 [2] addr drv_Nop1
 |_ram:0000000c [3] addr drv_GetPageSize
 |_ram:00000010 [4] addr drv_PageFlip
 |_ram:00000014 [5] addr drv_SwapBuffers
 |_ram:00000018 [6] addr drv_SetPalette
 |_ram:0000001c [7] addr drv_FillRect
 |_ram:00000020 [8] addr drv_CopyRect
 |_ram:00000024 [9] addr drv_PutPixel
 |_ram:00000028 [10] addr drv_GetPixel
 |_ram:0000002c [11] addr drv_BlockCopy
 |_ram:00000030 [12] addr drv_DrawLine
 |_ram:00000034 [13] addr drv_BlitTransparent
 |_ram:00000038 [14] addr drv_Nop2
 |_ram:0000003c [15] addr drv_BlitOpaque
 |_ram:00000040 [16] addr drv_DrawSprite
 |_ram:00000044 [17] addr drv_DrawSpriteAlt
 |_ram:00000048 [18] addr drv_Blit1bpp
 |_ram:0000004c [19] addr drv_CopyScanline
 |_ram:00000050 [20] addr drv_BlitRect
 |_ram:00000054 [21] addr drv_BlitRect
 |_ram:00000058 [22] addr drv_SetFontMetrics
 |_ram:0000005c [23] addr drv_DrawText
 |_ram:00000060 [24] addr drv_CopyScanlineBoth
 |_ram:00000064 [25] addr drv_Nop3

It is loaded dynamically at runtime.

Here are some of my findings:

1. Relocation and Dynamic Loading

The most immediate characteristic of this driver is its self-relocation mechanism. The function at index 0, drv_InitWithReloc, reveals that the code is designed to be position-independent but requires a one-time setup to function correctly.

; undefined drv_InitWithReloc(void)
ram:000001c2 e843ffffff CALL drv_InternalVideoSetup
ram:000001c7 0bc0 OR EAX,EAX
ram:000001c9 7411 JZ LAB_000001dc
ram:000001cb b968000000 MOV ECX,0x68 ; 26 entries * 4 bytes
ram:000001d0 c1e902 SHR ECX,0x2
ram:000001d3 8bfb MOV EDI,EBX ; EBX is likely the load address
LAB_000001d5:
ram:000001d5 011f ADD dword ptr [EDI],EBX
ram:000001d7 83c704 ADD EDI,0x4
ram:000001da e2f9 LOOP LAB_000001d5

The routine iterates through the initial 26-entry jump table, adding the base load address (passed in EBX) to each entry. This implies the main executable allocates a block of memory, loads this binary blob, and then calls the first instruction with the allocated address in EBX to “patch” the driver into validity.

2. Software Line-Doubling

A distinct feature of the drawing routines is the implementation of software-based scanline doubling. An examination of drv_FillRect and drv_CopyScanline shows a specific memory access pattern:

; From drv_FillRect
ram:000002b8 2bfa SUB EDI,param_2
ram:000002ba 81c700040000 ADD EDI,0x400
; ... repeat store operation ...
; From drv_CopyScanline
ram:000006b3 81c500080000 ADD EBP,0x800

The driver operates with a virtual stride of 1024 bytes (0x400). However, primitive drawing operations write to the target offset Y, add 0x400 to write the same data to Y+1, and then add 0x800 to the base pointer to advance to the next logical line.

Rather than relying on hardware scaling, the driver “doubles” the height by drawing every line twice explicitly in VRAM.

3. Shift-JIS Character Support

The driver contains a robust text rendering engine, specifically tailored for Japanese text. drv_DrawText (offset 0x005c) performs boundary checks consistent with Shift-JIS encoding:

ram:0000087d 3c81 CMP param_1,0x81
ram:0000087f 7216 JC LAB_00000897 ; ASCII/Half-width
ram:00000881 3c9f CMP param_1,0x9f
ram:00000883 7608 JBE LAB_0000088d ; Shift-JIS Lead Byte

4. Hardware Port Utilization

The driver manipulates the Towns’ unique video hardware directly via I/O ports, rather than relying solely on BIOS calls.

Ports 0x440/0x442: Used in drv_PageFlip to toggle display pages, indicating a double-buffered rendering setup.
Ports 0xFD90-0xFD9F: Accessed in drv_SetPalette. These correspond to the FM Towns palette registers.
Ports 0x58/0x5A: The drv_InternalVideoSetup function writes to these ports, which usually control the CRTC (Cathode Ray Tube Controller) priority and layer mixing, likely ensuring the graphical layer used by the game overlays correctly on top of the system background.

Not all of this has been fact-checked nor am I an expert at FM-Towns.

Ghidra Lessons

rogerswaggoner@gmail.com (Roger Waggoner) — Tue, 18 Nov 2025 03:33:59 -0500

I’ve been doing a lot of reversing lately and learning a ton while doing it, I’m going to try to document and maybe share some knowledge.

Segmented memory is really hard and the tools are bad. Unless you have good reason, stay away from x86 dos-era binaries using real mode. I will check back in on this in 5 years and see if the tooling has improved. A lot of games were ported to other platforms, so this can sometimes be avoided just by working on a different version of the same game.
Ghidra is really great and easily extensible. But it has some issues along with a steep learning curve.

Using a union with uint8_t (byte) array greatly helped improve decompilation output:

Before:

The + -10 part is because the .partySlotToCharacterIndex

After:

A few other tips:

Start bottom up. Identify known functions and begin propagating types upwards. Even in old executables you will find plenty of system library calls that are used as the foundational building blocks of the program.
Make usage of the version control feature, and checkin regularly.
Use auto-analysis to propagate analyses after working on the program.
Use the diff tool to diff the results of auto-analysis. You can diff against the checked in version, but make sure you actually select the latest version rather than it from the listing. This is good to even see the results of various auto-analyses options.
The documentation is very good
LLMs seem to fair poorly with the output of the decompilation. It often has false positives, red herrings, etc., that they latch onto. On the other hand, the disassembly alone seems to be fine.
Massive majority of articles, plugins, and so on for Ghidra are related to malware analysis, vulnerability research, etc.,
Be careful of constants that happen to have the same address as pointers. This has bitten me a lot!

MicroRules: A Tiny Expression Language for C#

rogerswaggoner@gmail.com (Roger Waggoner) — Sun, 29 Jun 2025 00:00:00 +0000

I built MicroRules because I got tired of writing verbose conditional logic for business rules that changed frequently. What started as a simple expression parser evolved into a full-featured domain-specific language that compiles string expressions into strongly-typed, executable C# functions.

The Problem

Business logic is messy. You have discount calculations, shipping rules, access control, content moderation - all these rules that seem simple but get complex fast. Traditional approaches either scatter this logic throughout your codebase or force you into heavy rule engines that are overkill for most scenarios.

I wanted something lightweight that could express rules compactly while maintaining strong typing and performance.

The Solution

MicroRules takes string expressions and compiles them into actual .NET functions at runtime. Not interpreted - compiled. The result is a tiny DSL that’s both readable and fast.

Here’s a simple discount rule:

var discountRule = MicroRules.Compile<SelfFunc<Customer, double>>("SpendTotal > 100 ? 0.1 : 0");
double discount = discountRule(customer);

Pattern Matching for Complex Logic

The real power comes from pattern matching. Take shipping costs - traditionally a nightmare of nested if-statements:

(zone, weight, service, membership) -> {
(Domestic, <= 5, Express, Premium): baseCost * 0.8,
(International, _, _, Premium): baseCost * 1.2,
(_, > 20, Ground, _): baseCost + (weight - 20) * surchargeRate,
(Remote, _, _, _): baseCost * 1.5,
_: baseCost
}

This tuple-based pattern matching supports exact values, range comparisons (<= 5, > 20), and wildcards (_). First match wins, so you can layer specific cases over general ones.

LINQ Integration

Modern business rules often involve collections. MicroRules supports LINQ operations with lambda expressions:

// Block checkout if any item is unavailable
cart.items.Any(i => i.inventory <= 0)
// Check if user has required permissions
user.permissions.All(p => p.level >= AdminLevel && p.active)

Collection Contains Patterns

(patientAge, weight, condition, allergies) -> {
(>= 65, _, Hypertension, ['ace-inhibitor']): alternativeDose * 0.5,
(< 18, < 50, _, _): pediatricDose,
(_, >= 100, Diabetes, _): standardDose * 1.2,
_: standardDose
}

The ['ace-inhibitor'] checks if the allergies collection contains that specific value. Works with arrays, lists, dictionaries, and even strings (substring search).

Technical Implementation

Under the hood, MicroRules uses a three-stage compilation pipeline:

Lexer - Tokenizes expressions with support for string literals, numbers, operators, and identifiers
Parser - Recursive descent parser building LINQ Expression trees with proper operator precedence
Compiler - Wraps compiled expressions in strongly-typed delegates

The parser handles some tricky features:

Enum inference - weaponType == Sword automatically infers WeaponType.Sword from context
Mixed arithmetic - Integers and doubles play nicely together
Extension methods - Full LINQ support plus custom extension method discovery
Deep member access - user.profile.settings.theme just works

Type Safety and Performance

Everything is strongly typed. The compiler validates member access, enum values, and type conversions at compile time. Invalid expressions throw clear error messages before your code ever runs.

Performance-wise, compiled expressions run at native .NET speed. The compilation cost is paid once - after that, it’s just a function call.

Usage Patterns

I designed MicroRules around two main usage patterns:

Custom delegates for multi-parameter scenarios:

public delegate double PricingRule(Order order, double basePrice);
var rule = MicroRules.Compile<PricingRule>("order.Items.Any(i => i.Category == Premium) ? basePrice * 1.2 : basePrice");

SelfFunc for single-parameter cases where you want implicit property lookup:

var rule = MicroRules.Compile<SelfFunc<Customer, bool>>("Age >= 18 && CreditScore > 600");
bool eligible = rule(customer);

The “self” in SelfFunc enables that clean syntax where Age automatically resolves to customer.Age.

*MicroRules is open source and available on GitHub.

When lerp isn't linear

rogerswaggoner@gmail.com (Roger Waggoner) — Sat, 13 Jul 2024 04:01:40 -0400

You will frequently come across code in the wild that vaguely resembles this:

// Most engines will provide a lerp for you
T lerp(T a, T b, float t) {
 return a + t * (b - a);
}

void update(float delta) {
 position = lerp(position, destination, delta);
}

Perhaps even multiplying the speed by delta in the t parameter.

At face value, it seems to work, but it’s probably not doing what you think it’s doing. Lerp is not a smoothing function, it is for linearly interpolating a value across a line from a to b by the factor t. If you are repeatedly changing the a and/or b values, you are using lerp incorrectly — it is no longer linear.

What you are doing is applying a telescoping function — it is a geometric series. position will nonlinearly(asymptotically) approach destination, which creates the desired appearance of smoothing.

What to use instead?

If you just want to move a towards b at a constant speed, you do not want or need lerp. The Godot engine provides a function named move_toward that does exactly what you want. This is how it’s implemented in the C++ source:

static double move_toward(double p_from, double p_to, double p_delta) {
 return abs(p_to - p_from) <= p_delta ? p_to : p_from + SIGN(p_to - p_from) * p_delta;
}

What if you want to smoothly move `a` towards `b`?

Game Programming Gems IV(2004) book, Chapter 1.10 “Critically Damped Ease-In/Ease-Out Smoothing” describes an implementation of smoothing based on a critically damped spring model.

I’m borrowing this implementation from Unity’s reference source code for demonstration:

public static float SmoothDamp(float current, float target, ref float currentVelocity, float smoothTime, float maxSpeed, float deltaTime)
{
 smoothTime = Mathf.Max(0.0001F, smoothTime);
 float omega = 2F / smoothTime;

 float x = omega * deltaTime;
 float exp = 1F / (1F + x + 0.48F * x * x + 0.235F * x * x * x);
 float change = current - target;
 float originalTo = target;

 // Clamp maximum speed
 float maxChange = maxSpeed * smoothTime;
 change = Mathf.Clamp(change, -maxChange, maxChange);
 target = current - change;

 float temp = (currentVelocity + omega * change) * deltaTime;
 currentVelocity = (currentVelocity - omega * temp) * exp;
 float output = target + (change + temp) * exp;

 // Prevent overshooting
 if (originalTo - current > 0.0F == output > originalTo)
 {
 output = originalTo;
 currentVelocity = (output - originalTo) / deltaTime;
 }

 return output;
}

Unity’s documentation defines the parameters as following:

Parameter	Description
current	The current value.
target	The target value.
currentVelocity	Use this parameter to specify the initial velocity to move the current value towards the target value. This method updates the currentVelocity based on this movement and smooth-damping.
smoothTime	The approximate time it takes for the current value to reach the target value. The lower the smoothTime, the faster the current value reaches the target value. The minimum smoothTime is 0.0001. If a lower value is specified, it is clamped to the minimum value.
maxSpeed	Use this optional parameter to specify a maximum speed. By default, the maximum speed is set to infinity.
deltaTime	The time since this method was last called. By default, this is set to `Time.deltaTime`.

I find it practical to define smooth_time as distance / desired_velocity, as we often know the velocity we want when smoothing. If you want it to also ease out, apply sqrt to smooth_time. Additionally, you’ll want to set max_speed to desired_velocity.

Godot Plugin Tool Script Type Detection

rogerswaggoner@gmail.com (Roger Waggoner) — Thu, 11 Jul 2024 14:20:30 -0400

When you have a tool script attached to a node in Godot’s editor, it will run both while you are editing the scene, and when it is attached to the editor itself. You can differentiate between which ‘kind’ is runnig by checking the viewport:

if (GetViewport()?.Name != "root") {
 return;
}

The edited scene will not have the root viewport as its nearest viewport.

Blender Tip 1

rogerswaggoner@gmail.com (Roger Waggoner) — Sat, 01 Jun 2024 16:47:31 -0400

In my spare time I do some hard edge modeling & level design in Blender. As anyone who has used Blender is aware, Blender is rather difficult to learn. I’ve been using it for a very long time off and on, and thought I’d share some tips. To start this out, here’s a tip for detecting faces with incorrect normals.

First, click the ‘Overlays’ dropdown in the top-right of the 3D editor, and toggle on ‘Face Orientation’:

Seems simple so far, but this will add a highlight to both faces with their normal pointing towards and away from the camera. We just want the faces with the normals pointing away, so we must go into the preferences(Edit → Preferences). Select the ‘Themes’ tab on the left, click the ‘3D Viewport’ tab on the right to toggle it open. Scroll down to ‘Face Orientation Front’:

What you want to do is lower the alpha value of this color to 0, so that there is no overlay for faces that are oriented towards us. Save your preferences.

To make sur the overlay is enabled at startup, you must save the scene as your startup file(File → Defaults → Save Startup File).

Here’s an example of how it should look, with faces that are pointing away appearing red after I’ve removed a face from the default cube:

Very handy for level design to quickly find faces that need their normal flipped.

Texture Blending 2(With Godot)

rogerswaggoner@gmail.com (Roger Waggoner) — Sat, 23 Dec 2023 23:53:15 -0500

This is a direct continuation of the previous post.

I created a plane mesh instance which I exported to Blender for subdividing and UV coloring. We will be using the colors as weights for both blending and layering.

I found Blender to be a bit troublesome for manipulating the colors of individual vertices, perhaps I’ll create a tool for the Godot editor in the future to easily handle this.

On the edges will be 100% our R texture, and 100% our G texture in the middle. Inbetween I added yellow vertices for a nice blend of an overlapping RG layer.

shader_type spatial;
render_mode blend_mix,depth_draw_opaque,cull_back,diffuse_burley,specular_schlick_ggx;

// Macro to define a uniform group for a material layer.
// Each layer (R, G, B) will have its own set of uniforms for various material properties.
#define DEFINE_UNIFORM_GROUP(suffix) \
 group_uniforms Material##suffix; \
 uniform vec4 albedo##suffix : source_color = vec4(1.0); \
 uniform sampler2D texture_albedo##suffix : source_color,filter_linear_mipmap,repeat_enable; \
 uniform float roughness##suffix: hint_range(0,1) = 1.0; \
 uniform sampler2D texture_metallic##suffix: hint_default_white,filter_linear_mipmap,repeat_enable; \
 uniform vec4 metallic_texture_channel##suffix; \
 uniform sampler2D texture_roughness##suffix: hint_roughness_r,filter_linear_mipmap,repeat_enable; \
 uniform float specular##suffix = 0.5; \
 uniform float metallic##suffix = 0.0; \
 uniform sampler2D texture_normal##suffix: hint_normal,filter_linear_mipmap,repeat_enable; \
 uniform float normal_scale##suffix: hint_range(-16,16) = 1.0; \
 uniform sampler2D texture_ambient_occlusion##suffix: hint_default_white, filter_linear_mipmap,repeat_enable; \
 uniform vec4 ao_texture_channel##suffix = vec4(1.0, 0.0, 0.0, 0.0); \
 uniform float ao_light_affect##suffix = 0.0; \
 uniform sampler2D texture_heightmap##suffix: hint_default_black,filter_linear_mipmap,repeat_enable; \
 uniform float heightmap_scale##suffix = 5.0; \
 uniform vec2 heightmap_flip##suffix; \
 group_uniforms;

// Define uniforms for three material layers: R, G, and B.
DEFINE_UNIFORM_GROUP(R)
DEFINE_UNIFORM_GROUP(G)
//DEFINE_UNIFORM_GROUP(B)


uniform vec3 uv1_scale = vec3(1.0);
uniform vec3 uv1_offset;
uniform vec3 uv2_scale = vec3(1.0);
uniform vec3 uv2_offset;

// Uniform to control the sharpness of the blend.
uniform float BlendSharpness: hint_range(1.0,10.0) = 3.0;
uniform sampler2D texture_noise;


void vertex() {
 UV=UV*uv1_scale.xy+uv1_offset.xy;
}

struct MaterialProperties {
 vec4 albedo;
 float roughness;
 vec4 metallic_texture_channel;
 float specular;
 float metallic;
 float normal_scale;
 vec4 ao_texture_channel;
 float ao_light_affect;
 float heightmap_scale;
 vec2 heightmap_flip;

 vec2 uv;
 vec3 vertex;
 vec3 normal;
 vec3 tangent;
 vec3 binormal;
};

struct ProcessMaterialOut {
 vec3 albedo;
 float metallic;
 float roughness;
 float specular;
 vec3 normal_map;
 float normal_map_depth;
 float ao;
 float ao_light_affect;
 float depth;
 float height;
};

// Function to process material properties and textures for a layer.
// Applies texture sampling and calculations to derive final material attributes.
ProcessMaterialOut process_material(MaterialProperties props, sampler2D texture_albedo, sampler2D texture_heightmap,
 sampler2D texture_metallic, sampler2D texture_roughness, sampler2D texture_normal,
 sampler2D texture_ambient_occlusion) {
 ProcessMaterialOut p_out;
 vec2 base_uv;
 {
 vec3 view_dir = normalize(normalize(-props.vertex) * mat3(props.tangent * props.heightmap_flip.x, -props.binormal * props.heightmap_flip.y, props.normal));
 float height = texture(texture_heightmap, props.uv).r;
 float depth = 1.0 - height;
 p_out.depth = depth;
 p_out.height = height;
 vec2 ofs = props.uv - view_dir.xy * depth * props.heightmap_scale * 0.01;
 base_uv=ofs;
 }

 vec4 albedo_tex = texture(texture_albedo,base_uv);
 p_out.albedo = props.albedo.rgb * albedo_tex.rgb;
 float metallic_tex = dot(texture(texture_metallic,base_uv), props.metallic_texture_channel);
 p_out.metallic = metallic_tex * props.metallic;
 vec4 roughness_texture_channel = vec4(1.0,0.0,0.0,0.0);
 float roughness_tex = dot(texture(texture_roughness,base_uv),roughness_texture_channel);
 p_out.roughness = roughness_tex * props.roughness;
 p_out.specular = props.specular;
 p_out.normal_map = texture(texture_normal,base_uv).rgb;
 p_out.normal_map_depth = props.normal_scale;
 p_out.ao = dot(texture(texture_ambient_occlusion,base_uv),props.ao_texture_channel);
 p_out.ao_light_affect = props.ao_light_affect;

 return p_out;
}

// Utility function to reconstruct the Z component of a normal vector from its X and Y components.
float reconstructZ(vec3 norm) {
 return sqrt(max(0.0, 1.0 - dot(norm.xy, norm.xy)));
}

// Macro to initialize material properties for a layer based on the defined uniforms.
#define DEFINE_MATERIAL_PROPERTIES(suffix) \
 MaterialProperties mat##suffix; \
 mat##suffix.albedo = albedo##suffix; \
 mat##suffix.roughness = roughness##suffix; \
 mat##suffix.metallic_texture_channel = metallic_texture_channel##suffix; \
 mat##suffix.specular = specular##suffix; \
 mat##suffix.metallic = metallic##suffix; \
 mat##suffix.normal_scale = normal_scale##suffix; \
 mat##suffix.ao_texture_channel = ao_texture_channel##suffix; \
 mat##suffix.ao_light_affect = ao_light_affect##suffix; \
 mat##suffix.heightmap_scale = heightmap_scale##suffix; \
 mat##suffix.heightmap_flip = heightmap_flip##suffix; \
 \
 mat##suffix.uv = UV; \
 mat##suffix.vertex = VERTEX; \
 mat##suffix.normal = NORMAL; \
 mat##suffix.tangent = TANGENT; \
 mat##suffix.binormal = BINORMAL; \
 \
 out##suffix = process_material(mat##suffix, texture_albedo##suffix, texture_heightmap##suffix, texture_metallic##suffix, \
 texture_roughness##suffix, texture_normal##suffix, texture_ambient_occlusion##suffix);


void fragment() {
 // Output structures for each layer (R, G, B) after processing their material properties.
 ProcessMaterialOut outR;
 ProcessMaterialOut outG;
 //ProcessMaterialOut outB;

 // Initialize material properties for each layer.
 {
 DEFINE_MATERIAL_PROPERTIES(R)
 DEFINE_MATERIAL_PROPERTIES(G)
 // DEFINE_MATERIAL_PROPERTIES(B)
 }

 // Ensure that vertex colors are non-negative.
 vec3 vcolor = max(COLOR.rgb, vec3(0.0));

 // Calculate blending weights for each layer.
 // These weights are based on the red, green, and the minimum of red and green components of the vertex color.
 float weightR = vcolor.r;
 float weightG = vcolor.g;
 float weightRG = min(weightR, weightG);

 float adjWeightR = pow(max(weightR - weightRG, 0.0), BlendSharpness);
 float adjWeightG = pow(max(weightG - weightRG, 0.0), BlendSharpness);
 float adjWeightRG = pow(weightRG, BlendSharpness);

 float totalWeight = adjWeightR + adjWeightG + adjWeightRG;

 // Normalize the weights so they sum up to 1.
 float normWeightR = adjWeightR / totalWeight;
 float normWeightG = adjWeightG / totalWeight;
 float normWeightRG = adjWeightRG / totalWeight;

 // Determine the step function for layer height comparison.
 // This is used to create a sharp transition between layers based on their height.
 float stepRG = step(outR.height, outG.height);

 // Blend the albedo, roughness, specular, normal map, and other properties from each layer.
 // The blending is based on the normalized weights and the height-based step function.
 // Each property is blended separately.
 vec3 layerColorR = outR.albedo * normWeightR;
 vec3 layerColorG = outG.albedo * normWeightG;
 vec3 layerColorRG = mix(outR.albedo, outG.albedo, stepRG) * normWeightRG;

 float layerRoughnessR = outR.roughness * normWeightR;
 float layerRoughnessG = outG.roughness * normWeightG;
 float layerRoughnessRG = mix(outR.roughness, outG.roughness, stepRG) * normWeightRG;

 float layerSpecularR = outR.specular * normWeightR;
 float layerSpecularG = outG.specular * normWeightG;
 float layerSpecularRG = mix(outR.specular, outG.specular, stepRG) * normWeightRG;

 // Normal map blending is handled with care to preserve correct surface details.
 vec3 layerNormalR = outR.normal_map ;
 layerNormalR.z = reconstructZ(layerNormalR);
 layerNormalR *= normWeightR;

 vec3 layerNormalG = outG.normal_map;
 layerNormalG.z = reconstructZ(layerNormalG);
 layerNormalG *= normWeightG;

 // This is correct, the step creates a sharp transition, no lerp happens.
 vec3 layerNormalRG = mix(outR.normal_map, outG.normal_map, stepRG);
 layerNormalRG.z = reconstructZ(layerNormalRG);
 layerNormalRG *= normWeightRG;

 // Blend the normal map depth, ambient occlusion, and AO light affect from each layer.
 float layerNormalDepthR = outR.normal_map_depth * normWeightR;
 float layerNormalDepthG = outG.normal_map_depth * normWeightG;
 float layerNormalDepthRG = mix(outR.normal_map_depth, outG.normal_map_depth, stepRG) * normWeightRG;

 float layerAoR = outR.ao * normWeightR;
 float layerAoG = outG.ao * normWeightG;
 float layerAoRG = mix(outR.ao, outG.ao, stepRG) * normWeightRG;

 float layerAoLightR = outR.ao_light_affect * normWeightR;
 float layerAoLightG = outG.ao_light_affect * normWeightG;
 float layerAoLightRG = mix(outR.ao_light_affect, outG.ao_light_affect, stepRG) * normWeightRG;

 // Final composition of the material properties.
 // The properties from each layer are added together based on their respective weights.
 ALBEDO = layerColorR + layerColorG + layerColorRG;
 ROUGHNESS = layerRoughnessR + layerRoughnessG + layerRoughnessRG;
 SPECULAR = layerSpecularR + layerSpecularG + layerSpecularRG;
 NORMAL_MAP = normalize(layerNormalR + layerNormalG + layerNormalRG);
 NORMAL_MAP_DEPTH = layerNormalDepthR + layerNormalDepthG + layerNormalDepthRG;
 AO = layerAoR + layerAoG + layerAoRG;
 AO_LIGHT_AFFECT = layerAoLightR + layerAoLightG + layerAoLightRG;
}

That’s a lot of code, but don’t be intimidated. It’s from the Standard Material 3D shader with the properties we want. The calculations were extracted to a function, and we use preprocessor macros to generate our layer code.

This could be extended to blending between three sub-materials, but it would go from 3 possible combinations to 7. That’s a lot of operations.

Our final output:

We can see where the yellow vertices are is a nice overlapping layer of dirt and stone which creates a pleasant layer to blend between the two.

The code we’re most interested in is after:

 // Initialize material properties for each layer.
 {
 DEFINE_MATERIAL_PROPERTIES(R)
 DEFINE_MATERIAL_PROPERTIES(G)
 }

The sub-materials are applied based on weighting for R, G, and RG. Recall that RG is our R+G height-based layered sub-material.

This code may be unfamiliar:

float stepRG = step(outR.height, outG.height);
[…]
mix(outR.roughness, outG.roughness, stepRG)

It’s just an optimization to skip conditionals. stepRG is always 0.0 or 1.0, therefore we’re always getting 100% of outR’s value or outG’s value based on the value in the height maps at our fragment’s location.

We use a sharpness parameter to control the sharpness of the blends between sub-materials:

float adjWeightR = pow(max(weightR - weightRG, 0.0), BlendSharpness);
float adjWeightG = pow(max(weightG - weightRG, 0.0), BlendSharpness);
float adjWeightRG = pow(weightRG, BlendSharpness);

Sharpness value of 1.0:

Sharpness value of 3.0:

To be able to properly weight & normalize our normal vectors, we have to reconstruct the Z parameter. Normal maps pack R&G(x, y) together. After reconstruction, we nlerp between them based on their respective vertex color weights. This probably doesn’t look too good if there’s a significant angle difference, but as this is for ground materials I’ll probably be OK.

vec3 layerNormalR = outR.normal_map ;
layerNormalR.z = reconstructZ(layerNormalR);
layerNormalR *= normWeightR;

vec3 layerNormalG = outG.normal_map;
layerNormalG.z = reconstructZ(layerNormalG);
layerNormalG *= normWeightG;

vec3 layerNormalRG = mix(outR.normal_map, outG.normal_map, stepRG);
layerNormalRG.z = reconstructZ(layerNormalRG);
layerNormalRG *= normWeightRG;
[…]
NORMAL_MAP = normalize(layerNormalR + layerNormalG + layerNormalRG);

Texture Blending(With Godot)

rogerswaggoner@gmail.com (Roger Waggoner) — Sat, 23 Dec 2023 04:16:50 -0500

We’re going to start by obtaining two textures that will showcase blending well, one texture will be approximately average height, and the other will have lots of highs and lows.

AmbientCG provides CC-0 textures.

For the first, we have some dirt: https://ambientcg.com/view?id=Ground042 And for the second a brick material: https://ambientcg.com/view?id=Bricks076A

We can start by creating a simple Godot shader to blend between two textures. I’ll be using a Godot primitive plane, and therefore its default UV coordinates will work fine for us. Create a MeshPrimitive node, assign a Plane shape, and set the material override as a new ShaderMaterial. Assign our new shader to that ShaderMaterial.¹

shader_type spatial;
uniform sampler2D textureA;
uniform sampler2D textureB;

void fragment() {
 vec4 colorA = texture(textureA, UV);
 vec4 colorB = texture(textureB, UV);
 float blenderFactor = UV.x;

 vec4 blendedColor = mix(colorA, colorB, blenderFactor);

 ALBEDO = blendedColor.rgb;
}

And we’re done! …No? Not good enough? Fine.

What if instead of using a simple mix we used something else to control the blending?

We can use the height maps of each material to control how they layer over each other like so:

shader_type spatial;
uniform sampler2D textureA;
uniform sampler2D textureB;
uniform sampler2D heightTexA;
uniform sampler2D heightTexB;

void fragment() {
 vec4 colorA = texture(textureA, UV);
 vec4 colorB = texture(textureB, UV);
 float heightA = texture(heightTexA, UV).r;
 float heightB = texture(heightTexB, UV).r;
 float blenderFactor = UV.x;

 vec4 blendedColor = mix(colorA, colorB, blenderFactor);
 // NOTE: this can be converted to a mix + step, as seen later.
 if (heightA >= heightB) {
 ALBEDO = colorA.rgb;
 } else {
 ALBEDO = colorB.rgb;
 }
}

And while that does produce a rather nice-looking result:

It’s not actually what we’re looking for. We can differentiate between the first as blending, and the second as layering. If we wanted to smoothly transition from our dirt to our bricks then, we could use both.

Assume that at UV.x = 0, we just have bricks. And at UV.x = 1, we have dirt. Between this, is our blend.

Therefore, we have three colors. Brick, BrickDirt, Dirt.

Therefore, for this post, we have our final shader code:

shader_type spatial;
uniform sampler2D textureA;
uniform sampler2D textureB;
uniform sampler2D heightTexA;
uniform sampler2D heightTexB;

vec3 triMix(vec3 colorA, vec3 colorB, vec3 colorC, float t) {
 vec3 mixAB = mix(colorA, colorB, t * 2.0); // Mix between colorA and colorB for t in [0, 0.5]
 vec3 mixBC = mix(colorB, colorC, (t - 0.5) * 2.0); // Mix between colorB and colorC for t in [0.5, 1]

 return mix(mixAB, mixBC, step(0.5, t)); // Blend between mixAB and mixBC at t = 0.5
}


void fragment() {
 vec4 colorA = texture(textureA, UV);
 vec4 colorB = texture(textureB, UV);
 float heightA = texture(heightTexA, UV).r;
 float heightB = texture(heightTexB, UV).r;
 float blendFactor = UV.x;

 // If substitued with step+mix
 vec3 layerColor = mix(colorB.rgb, colorA.rgb, step(heightB, heightA));
 ALBEDO = triMix(colorA.rgb, layerColor, colorB.rgb, blendFactor);
}

The blend itself could be controlled by adding more parameters to the three-way mix. We also aren’t limited to mix either. It’s common to use a texture to control the blending. For example, Valve’s Hammer makes use of a modulation texture.

For my purposes, however, this is exactly what I need, and will expand upon that in a future post.

Screenshot of the final node setup. ↩︎

Posts on ~

Ultima Underworld PSX outside a PlayStation: AbyssX

What is working

What is not working yet

What’s next

Reverse Engineering DOS Games on FM Towns

Why FM Towns?

Adding tracing to Tsugaru

Keeping trace sizes manageable

What’s next

Infinity FM-Towns Driver

1. Relocation and Dynamic Loading

2. Software Line-Doubling

3. Shift-JIS Character Support

4. Hardware Port Utilization

Ghidra Lessons

MicroRules: A Tiny Expression Language for C#

The Problem

The Solution

Pattern Matching for Complex Logic

LINQ Integration

Collection Contains Patterns

Technical Implementation

Type Safety and Performance

Usage Patterns

When lerp isn't linear

What to use instead?

What if you want to smoothly move a towards b?

Godot Plugin Tool Script Type Detection

Blender Tip 1

Texture Blending 2(With Godot)

Texture Blending(With Godot)

What if you want to smoothly move `a` towards `b`?