Decompile the Bolt and MBarrier overlays by eduardovra · Pull Request #146 · Xeeynamo/ff7-decomp

eduardovra · 2026-09-07T19:26:42Z

Two more magic overlays: BOLT (thunder) and MBARRIER (mabaria).

Also some renaming and restructuring as the magic overlays get better
understood. barrier, brizad and lv5deth are updated to follow.

Some of the variables were figured out from q-gears, others by poking
around in an emulator.

The two renderers share a footprint and nothing else, so the unions had no discriminator in the data. Names the flag bits, and updates barrier, brizad and lv5deth to match. Field readings cross-checked against Akari's q-gears_reverse notes.

Both overlays match in full.

Xeeynamo

Good work so far. I left a non exhausting review for things I'd like to see before geting this in. A few patterns I found while reviewing:

Avoid verbose comments in code. Especially LLM ones that just describes how the code reads. Those are generally more harmful than helpful.
A few field = field + 1 that could be simplified.
Try removing casts when possible. If a cast can't be removed, evaluate if the function/variable type could be changed.
I see a mix of local var declarations and assignments. For the sake of consistency with the rest of the code base, keep them separate.

Xeeynamo · 2026-09-08T07:57:39Z

+// Quad pass over ThunderRenderDesc1, 8 frames, mirrored per instance by the
+// random bits in unk1A. Not renamed: what it draws is not established.


Smells like LLM context?

Xeeynamo · 2026-09-08T08:00:33Z

+        nextFrame = (u16)effect->AnimationFrame + 1;
+        effect->AnimationFrame = nextFrame;
+        if (nextFrame == 8) {


Suggested change

nextFrame = (u16)effect->AnimationFrame + 1;

effect->AnimationFrame = nextFrame;

if (nextFrame == 8) {

effect->AnimationFrame++;

if (effect->AnimationFrame == 8) {

This can be simplified, and you couild even get rid of s16 nextFrame;. The same comment applies in other spots you're submitting.

Xeeynamo · 2026-09-08T08:04:10Z

+extern void* ThunderBufferPtr;
+extern ThunderData D_80162978[];
+extern ThunderPrimPage ThunderPrimBuffer[];
+extern u_long ThunderTexture[]; // 8bpp TIM + CLUT, uploaded on setup
+extern SpriteRenderDesc ThunderRenderDesc0;
+extern SpriteRenderDesc ThunderRenderDesc1;
+extern MATRIX ThunderModelMatrix;
+extern ModelRenderDesc ThunderModelDesc;


These should follow one of the two conventions for global or private vars: https://github.com/Xeeynamo/ff7-decomp/blob/main/STYLE.md

what I advise is using g_ThunderRenderDesc1 for now. Once the data comes fully imported, we could start renaminng these as render_desc1 (no need for thunder_ as prefix, as those vars would be private to the thunder overlay anyway)

Xeeynamo · 2026-09-08T08:05:35Z

+// Draws the embedded model through the model path, growing it by 0x200 a
+// frame from 1.0x to 2.875x across the 16 frames and dimming it over the
+// last 8.
+//
+// Flags 0x08 leave MODEL_DEPTH_CUE clear, so color is a grey level: it
+// steps from 0x80 down to 0x10, dimming the model from grey 128 to 16.
+//
+// The matrix holds a fixed orientation scaled by Scale -- m[0][0] and
+// m[2][1] take Scale, m[1][2] takes -Scale. Confirmed live: the other six
+// entries hold zero on all 16 frames.


I find these kind of comments hard to follow. The actual function is easier to read 😅 . Sometimes less is better.

Xeeynamo · 2026-09-08T08:06:57Z

+    MATRIX matrix;
+    ThunderData* effect = &D_80162978[D_8015169C];
+    s16 frame = effect->AnimationFrame;
+    u16* scale; // read through a pointer; a plain field read does not match


Suggested change

u16* scale; // read through a pointer; a plain field read does not match

s16* scale;

type change, also no need to justify decisions with comment in the source base.

Xeeynamo · 2026-09-08T08:07:28Z

+    ThunderModelMatrix.m[1][2] = -(s16)*scale;
+    ThunderModelMatrix.t[0] = (s32)effect->Pos.vx;
+    ThunderModelMatrix.t[1] = (s32)effect->Pos.vy;
+    ThunderModelMatrix.t[2] = (s32)effect->Pos.vz;


Suggested change

ThunderModelMatrix.m[1][2] = -(s16)*scale;

ThunderModelMatrix.t[0] = (s32)effect->Pos.vx;

ThunderModelMatrix.t[1] = (s32)effect->Pos.vy;

ThunderModelMatrix.t[2] = (s32)effect->Pos.vz;

ThunderModelMatrix.m[1][2] = -*scale;

ThunderModelMatrix.t[0] = effect->Pos.vx;

ThunderModelMatrix.t[1] = effect->Pos.vy;

ThunderModelMatrix.t[2] = effect->Pos.vz;

Xeeynamo · 2026-09-08T08:07:40Z

+    SetTransMatrix(&matrix);
+    ThunderBufferPtr = func_800D29D4(&ThunderModelDesc, g_cDb->unk70, 0xC, ThunderBufferPtr);
+    if (D_80062D98 == 0) {
+        effect->AnimationFrame = (u16)effect->AnimationFrame + 1;


Suggested change

effect->AnimationFrame = (u16)effect->AnimationFrame + 1;

effect->AnimationFrame++;

Xeeynamo · 2026-09-08T08:16:03Z

+    ThunderData* next;
+    ThunderData* effect = &D_80162978[D_8015169C];
+    s16 nextFrame;
+


Suggested change

ThunderData* next;

ThunderData* effect = &D_80162978[D_8015169C];

s16 nextFrame;

ThunderData* next;

ThunderData* effect;

s16 nextFrame;

effect = &D_80162978[D_8015169C]

split declarations and assignments. This allows us to move things around more easily without affecting the match.

Xeeynamo · 2026-09-08T08:26:55Z

+// PSX fixed point: 1.0 == 1 << FIXED_SHIFT. Angles: FIXED_ONE == a full turn.
+#define FIXED_SHIFT 12
+#define FIXED_ONE (1 << FIXED_SHIFT)


12 is a well known constant when dealing with rotations and GTE APIs on PS1. I don't think the macro belongs to the magic headers alone. And I don't think hiding these behind a macro is helpful at all. Reason is for these kind of math operations the operand must be explicit instead of the developer having to jump around the codebase to find what's the value of a specific macro.

More info here: https://psx.arthus.net/sdk/Psy-Q/DOCS/LIBREF46.PDF if you search for 4096.

If you want to go ahead and making a macro out of this, I may suggest as follow: https://github.com/Xeeynamo/sotn-decomp/blob/master/include/common.h#L125

Xeeynamo · 2026-09-08T08:28:49Z

+// back the next write position. Every magic overlay declares it this way.
+extern void* ThunderBufferPtr;
+extern ThunderData D_80162978[];
+extern ThunderPrimPage ThunderPrimBuffer[];


I noticed you have char BarrierPrimBuffer on the other overlay. This should probably have some consistency between magic overlays.

Simpler increments, fewer casts, split declarations, trimmed comments, and STYLE.md naming.

eduardovra · 2026-09-09T00:23:12Z

Good work so far. I left a non exhausting review for things I'd like to see before geting this in. A few patterns I found while reviewing:

Avoid verbose comments in code. Especially LLM ones that just describes how the code reads. Those are generally more harmful than helpful.

A few field = field + 1 that could be simplified.

Try removing casts when possible. If a cast can't be removed, evaluate if the function/variable type could be changed.

I see a mix of local var declarations and assignments. For the sake of consistency with the rest of the code base, keep them separate.

Thanks for the review @Xeeynamo. I've pushed some changes to address your concerns, let me know if I missed anything.

eduardovra added 2 commits September 7, 2026 16:12

magic: decompile the Bolt and MBarrier overlays

b5c88c5

Both overlays match in full.

eduardovra marked this pull request as ready for review September 7, 2026 19:30

Xeeynamo requested changes Sep 8, 2026

View reviewed changes

magic: address review feedback

4bcfe44

Simpler increments, fewer casts, split declarations, trimmed comments, and STYLE.md naming.

Navigation Menu

Decompile the Bolt and MBarrier overlays - #146

Decompile the Bolt and MBarrier overlays#146
eduardovra wants to merge 3 commits into
Xeeynamo:mainfrom
eduardovra:magic-overlays

eduardovra commented Sep 7, 2026

Uh oh!

Xeeynamo left a comment

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

Xeeynamo Sep 8, 2026

Uh oh!

eduardovra commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		// Quad pass over ThunderRenderDesc1, 8 frames, mirrored per instance by the
		// random bits in unk1A. Not renamed: what it draws is not established.

	u16* scale; // read through a pointer; a plain field read does not match
	s16* scale;

	effect->AnimationFrame = (u16)effect->AnimationFrame + 1;
	effect->AnimationFrame++;

Conversation

eduardovra commented Sep 7, 2026

Uh oh!

Xeeynamo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eduardovra commented Sep 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants