Call stack:

This issue is intended to track the progress of the built in randomizer functionality.

Elevator Pitch

At a high level, we want to take the pieces we like from our randomizer framework from SoH, and simplify and/or replace the pieces we dislike. SoH's randomizer v3 effort is already making lots of positive changes on the pieces we dislike, but is still well under way, and may or may not be finished before this effort begins.

Timeline

This will happen in 3 phases:

Phase 1: MVP

This will primarily involve overriding vanilla behavior to prevent vanilla items from being given, and associating each item give with a flag, either a built in flag that is already closely associated with the event, or if none exist a new ship_inf flag. A hook handler listening to these flags should then randomly pick an item to give from a hardcoded static list of items. The vanilla behavior PR is a great demonstration of how to achieve most of this.

Phase 2: Framework

Port over/simplify a lot of the constructs and framework we have on SoH's randomizer. This includes defining the tables for items, locations, hints, settings, creating a simple UI to configure and generate seeds. This will also include the first iteration of support for generating and using spoiler files

Phase 3: Logic

The major feat here will be full logic playthrough support.

As of 5/10/2024 I (ProxySaw) have begun some preliminary work to create an async item give queuing system, hooked up to a simple "check" flag based table.

It seems the controller joystick input is always at the max value in-game, so you can't walk or ESS, you're always either running at full speed or being idle.

However, on LUS's side, and in the Controller Mapping window, the joystick input has the proper values.

The camera encounters a noticeable artifact during new areas cutscenes or any cinematic shots that abruptly alter its position
It seems that the camera being suddenly teleported or snapped from one location to another, causing a rollback artifact due to interpolation

This is intended to track the remaining tasks blocking a 1.0/public release. Anyone with access is free to edit this list.

Must have

• Working CI for release artifacts @Archez
• #445 @garrettjoecox
• #422 @inspectredc
• Determine if we are going to revert to OTR or not for modding sake. - We are going to launch with o2r, mod authors will be pointed to a temporary branch that generates OTRs, they can use that until we have tooling for o2r.
• #436 @garrettjoecox
• #406
• #207
• Winning the Beaver Race crashes
• Shooting Skulltullas with Bow or Hookshot crashes
• soh.otr -> 2ship.otr and shipofharkinian.json -> 2ship2harkinian.json
• One full playthrough on windows
• One full playthrough on Mac or Linux

Should have

• #188 @KiritoDv
• #225
• #215
• #158
• #408 @Archez
• #448 Clang Format @briaguya-ai
• #214
• #60
• At least 10 playtesters actively playing for a week or two

Nice to have

• Various SFX are playing at the wrong pitch/modulation
• #159
• #404
• Controller visibility fix @briaguya-ai
• #388
• #323
• A few more general options in the save editor
• #228
• #155
• #237

you can see it on the right hand side

it's a little more visible when it's wider

Self explanatory. Should be able to just take form SoH.

MM uses various frame buffer effects in its rendering. The effects need to be restored or emulated through our F3D code.

• Kaleido world background - #127
• Motion blur - #127
• Shrinking window before next day transition - #127
• VisMono (grayscale/sepia filters) - #136
• Picto box picture (moving framebuffer data from GPU to CPU) - #189
• Deku Bubble reflections - #236

- [ ] Lens Actors when lens is active and camera pointed at a lens actor (preserves XLU draws that are outside the lens circle) - Moved to #408
- [ ] Some transitions - z_fbdemo_wipe5 is actually unused, so not really needed
- [ ] Support "noise" effect when motion blur is active - Moved to #158

All of these with the exception of picto box picture can most likely be achieved at the GPU side with the aid of custom FB opcodes in F3D

Picto box picture however needs to be moved to the CPU side and stored in the save context, so this will need an alternate solution. This would required copying the pixel data from the framebuffer out of the GPU back to CPU, then downscaled to the original games size 160x112 at I8 (then compressed to I5)

Grandmas story does not render due to an unimplemented opcode in LUS/F3D for gSPBgRect1Cyc/G_BG_1CYC

This opcode is similar to gSPBgRectCopy/G_BG_COPY, but the main difference is that it supports scaling. MM seems to not use scaling values outside of 1.0f, so we may be able to get away with a partial implementation that doesn't factor in scaling properly.
The case of grandmas story at least requires CI8 support, and MM uses the same opcode for RGBA16 too, so we need to make sure that multiple format/sizes are supported correctly.

Ref:

• http://n64devkit.square7.ch/n64man/gsp/gSPBgRectCopy.htm
• http://n64devkit.square7.ch/n64man/gsp/gSPBgRect1Cyc.htm

This is in the import_texture_i4 function, so likely a texture xml issue.

pls fix

Background

MM and OOT have assets that load a DL from a segment address provided by code. For OOT this is always a segment with a 0 offset. However MM is unique in that some assets also provide an offset value. This is used in a way where one DList can be stored in a segment, but assets can "index" into certain parts through creative placement of gsSPEndDisplayList.

An example of this can be seen here:

This DList is 4 instructions long, but essentially is used as two DLists due to the gsSPEndDisplayList. This DL is synced to segment 0x0C. Then assets control which "DL" they get by setting the segment offset. 0x0C000000 would execute the first half, where as 0x0C000010 would execute the second half.

The Problem

Where this becomes a problem is with our definition of Gfx words being uintptr_t instead of uint32_t. On 64bit machines, the size of Gfx is double compared to 32bit/N64 hardware. This means that segment offset values are invalid/index to the wrong location.

With the example above, 0x0C000010 has an offset of 0x10. Gfx has a size of 0x8 on 32bit and a size of 0x10 on 64bit. This means that the original offset of 0x10 is meant to index the segment address by 2, but on a 64bit machine this translates into only an index of 1.

Possible solutions / Proposals

Option 1: Exporter Fix

We could updated the exporter to adjust the segment offset for DList lookups based on the system performing the export. This would allow everything to work as expected without any changes in 2ship/Fast3D.

Example of proposed changes: Archez/OTRExporter@8ac66fe

Pros:

• Keeps Fast3D ignorant and 2ship

Cons:

• Prevents portability of exported OTRs from working on opposite architecture machines (OTRs generated on a 64bit machine will only work on a 64bit machine

We would also probably need to track in the OTR what architecture was used to create it so we can warn/notify when it is used on an incorrect machine.

Option 2: 2ship/Fast3D fix

We could change Fast3D to handle adjusting the segment value for DList lookups at render time. This would require us to adjust our existing 64bit modified segment values used by the master gfx DLs to be forced as 32bit sized offsets.

Example of proposed changes (also look at the LUS submodule change): Archez@6d479a8

Pros:

• Preserves portability of generated OTRs

Cons:

• Requires Fast3D to handle and be aware of the Gfx size difference
• Requires 2ship and other ports using LUS be aware that DList segment values must be in the "32bit size"

Option 3: New custom opcode

We could add a new custom DL opcode for use by the exporter when encountering DList segment addresses. This opcode can then signal to Fast3D to perform the offset adjustment strictly for address coming from the OTR.

Example of proposed changes: Archez/libultraship@552e192 + Archez/OTRExporter@4c1a36b

Pros:

• Preservces OTR portability
• Keeps segment valus coming from 2ship code using their true offset values unmodified

Cons:

• Yet another custom opcode to manage

Option 4: Same opcode with extra custom flag

Similar to option 3, however, instead of adding a new opcode we can leverage unused space in the original G_DL opcode to set a flag (16 bits of free space through gsDma1p l argument). This flag can then be used by Fast3D to perform the offset adjustment. A new macro can be used to set the flag into the command.

Example of proposed changes: Archez/libultraship@057d374 + Archez/OTRExporter@4c1a36b

Pros:

• All from option 3
• No new opcodes

Cons:

• Technically squeezes in custom flags into an existing opcode, but should be safe assuming this bit range is truly unused in N64 hardware (it is at least unused in LUS)

GFX Stack shows GetItem_DrawPotion as top item in the stack.

It seems that color dithering is not implemented at all and alpha dithering is not following n64 spec. This is used by various effects like dirt/snow dust effects, motion blur, etc.

This will require shader level support in Fast3D, there are good discussions about the specs/solutions from the GlideN64 repo gonetz/GLideN64#2173

Here is how these effects look in emulator:

This only happens on debug mode, an assertion failure from ImGui EndFrame?

A couple seconds after midnight of the final day (when the digital clock starts displaying), an unknown memory overflow happens that leads to corruption of some global values. Two noticable values that get modified are

s16 gCfbWidth;
s16 gCfbHeight;

These values are used often with scissor commands/framebuffer effects, so the analog clock looks as if it disappears (due to bad scissor values).

I'm not sure what is the exact cause, but looking at where gcfbWidth is declared, its right after

u64* gGfxSPTaskOutputBufferLoRes[0x3000];
void* gGfxSPTaskOutputBufferEndLoRes;

So maybe one of these is being overflowed?

CKeyframe is not implemented in ZAPD, the exporter, or the importer

Anyone else that has more information on this please provide it

It seems like torches do not have a texture applied to them.

Port:

N64:

There is nothing obvious among the changes we have made to prevent this. My guess is it's cutscene import related, as there is a check in Cutscene_HandleEntranceTriggers for gSaveContext.gameMode == GAMEMODE_TITLE_SCREEN

After showing the Nintendo 64 logo, you should see the following:

Open reg editor and set SREG(0) = 3

If you continually debug warp over and over again, you will see the green bar, which represents THA_GetRemaining(GameState->tha) goes into the negative.

According to the source of TwoHeadArena.c this should be considered a crash, but does not actually crash the game

/**
 * @return true if the Two Head Arena has overflowed, false otherwise
 */
u32 THA_IsCrash(TwoHeadArena* tha) {
    return THA_GetRemaining(tha) < 0;
}

"Wipe effects" aren't widescreen compatible
Effect such as ocarina and wipe effect aren't widescreen compatible

DONE: #219
DONE: #221

Will be resolved by

• #402
• #403

These guys

We can start from here, but I would like it to outline what guidelines and patterns to follow for things like:

• Adding code to the CPP codebase
• Adding code in src/
• Modifying/Removing code in src/
• Commenting practices
• Variable & file naming conventions for CPP codebase
• Variable naming conventions in src/
• When to use hooks, when to use cvars, and when to augment the original source code (and in which cases it's okay)
• When is it okay to enable a cvar by default
• etc

The last thing in the graphics stack is it attempting to render ovl_Dm_Tsg (masks scrolling by as Link falls)

There are also a few resource manager misses leading up to this

[error] Failed to load resource file at path

The smoke effect that comes out of the Romani Ranch house chimney is not rendering correctly.
On Windows I get the following:

The smoke is blue and is positioned/angled in the wrong spot.

On Mac I have seen this cause vertex explosion with the scene geometry.

This is what it should look like from PJ64 as reference:

Update:

As of #472 a temporary workaround has been put in place causing much less things to look wrong. If you see anything else not documented here please continue adding screenshots

Emulator
https://discord.com/channels/808039310850130000/1200211692257292419/1201346772551876679

Port
https://discord.com/channels/808039310850130000/1200211692257292419/1201346888457273365

Port:
Angry lion:

Angry lion with a light source:

The easiest way to reproduce this is to simply debug warp to termina field twice.

This also happens without debug warping, if you exit from south clock town to termina 4-5 times you will crash on transition, sometimes on the way to termina, sometimes on the way to clock town.

Upon the second time entering, you can see memory corruption has started occurring, affecting the title card

Temporary workaround here:
#74

The negative side effect of this workaround is that skull kid no longer fades into view in the opening cutscene.

Narrowed it down to the gsDPLoadMultiBlock command in this DL

Gfx sSongOfStormsMaterialDL[] = {
    gsDPPipeSync(),
    gsDPSetTextureLUT(G_TT_NONE),
    gsDPSetRenderMode(G_RM_PASS, G_RM_CLD_SURF2),
    gsDPSetEnvColor(50, 50, 0, 0),
    gsSPClearGeometryMode(G_CULL_BACK | G_FOG | G_LIGHTING | G_TEXTURE_GEN | G_TEXTURE_GEN_LINEAR),
    gsDPSetCombineLERP(TEXEL1, TEXEL0, PRIM_LOD_FRAC, TEXEL0, TEXEL1, TEXEL0, PRIM_LOD_FRAC, TEXEL0, PRIMITIVE,
                       ENVIRONMENT, COMBINED, ENVIRONMENT, COMBINED, 0, PRIMITIVE, 0),
    gsDPLoadTextureBlock(sSongOfStormsEffectTex, G_IM_FMT_I, G_IM_SIZ_8b, 64, 64, 0, G_TX_NOMIRROR | G_TX_WRAP,
                         G_TX_NOMIRROR | G_TX_WRAP, 6, 6, 3, 1),
    gsDPLoadMultiBlock(sSongOfStormsEffectTex, 0x0000, 1, G_IM_FMT_I, G_IM_SIZ_8b, 64, 64, 0, G_TX_NOMIRROR | G_TX_WRAP,
                       G_TX_NOMIRROR | G_TX_WRAP, 6, 6, 2, G_TX_NOLOD),
    gsSPEndDisplayList(),
};

Possibly related to #82
Message box for trying a game doesn't show anything and softlocks. Message_GetState is returning 0 since the msgLength is also 0, resulting in no text.

This includes things such as docs which only pertain to decomp

This was mostly used as a stand-in name, since we were undecided on the name.

The current save system mostly works, but doesn't have support for any sort of migrations, or handling of binary (emulator) saves.

Optimally, we still keep the simplicity of just relying on nlohmann::json to do the heavy lifting, and keep our code on top of it to a minimum

Probably needs a cache reset or whatever?