Documentation

Engine lines

Engine lines change how the Windows layer underneath Porthole behaves, for example swap-coverage = wide or env.MADEIRA_FEX_AVX = 1. There are 915 of them. Most games need none.

How to use one

  1. Open the game in Porthole and go to its settings.
  2. Under Starting, tap This game’s engine lines.
  3. Type the line, one per line, in the form key = value, then start the game again.

A line there applies to that game only and wins over the app-wide madeira.cfg. A line that starts with env. sets an environment variable for the game. These are for finding and working around problems; a wrong value can stop a game from starting. Remove the line to undo it.

Memory & JIT pool

arena-mb Number

madeira.cfg arena-mb = N

Type: Number · Default: 0

arena-mb = 0
avail-phys On/off

Report the memory left before the app's limit as available

Default off. 1: Windows programs' available physical memory (GlobalMemoryStatusEx) is what remains before Madeira's memory limit instead of the phone's free memory, so Chromium (Social Club, Steam) frees caches below 1000 MB and 400 MB left, and a game can see memory running out. Set it in the game's own file; read at session start.

Type: On/off · Default: 0

avail-phys = 1
avail-phys-cef-mb Number

Available memory Chromium sees (MB)

0 (default): off. N: Social Club's SocialClubHelper.exe and Steam's steamwebhelper.exe see at most N MB of available physical memory, nobody else (the game and the launcher keep the real figure). Below 400 (e.g. 300) Chromium reports critical memory pressure every 5 s and purges caches and garbage; 400-999 (e.g. 900), moderate every 10 s. Independent of avail-phys. Set it in the game's own file; read at session start.

Type: Number · Default: 0

avail-phys-cef-mb = 0
donor-only On/off

Donor pool without a swap file

on (the default), donor-pool-mb set and swap-mb unset start the swap tier with the donor pool as its only stage: no swap file is made, and memory the pool cannot cover stays normal app memory (iOS compresses it inside the app's limit). 0: without swap-mb the donor pool is not started, as before. Read at launch.

Type: On/off · Default: 1

donor-only = 1
donor-pool-guard One of a list

Donor pool: memory-pressure guard

what iOS's memory-pressure notification does to the pool. Unset: nothing, the pool is spent like MeloNX's (on an 8 GB phone the critical notification refused 502 takes and left 2.6 GB of the pool unused while the title's own memory, compressed, filled the app's limit; donated pages are the extension's to compress, not the app's). 1: a critical notification stops takes. 2: warning and critical (the old behaviour).

Type: One of a list · Default: 0 · Choices: , Off (spend the pool), 1, Stop at critical pressure, 2, Stop at warning

donor-pool-guard = 
donor-pool-kind One of a list

Donor pool memory kind

how the extension creates each donated region. ledger (the default): a named memory entry tagged to the extension's ledger. purgeable: a purgeable allocation in the extension named by a memory entry (the way MeloNX donates RAM). Everything else in the tier is the same, so the two can be compared.

Type: One of a list · Choices: , Ledger-tagged entry (default), purgeable, Purgeable allocation

donor-pool-kind = 
donor-pool-mb One of a list

Donor pool size

RAM for the swap tier that is not counted against Madeira's limit, donated by the MadeiraMemoryHost extension (512 MB regions, created untouched, handed over, then the extension exits). With swap-mb it is the swap tier's first stage, taken before the swap file; without swap-mb it is the only stage ( donor-only, madeira.cfg donor-only = 0 turns that off) and what it cannot cover stays normal app memory. Taken while free RAM stays above MADEIRA_DONOR_POOL_MARGIN_MB and iOS reports no memory pressure. Off by default; read at launch.

Type: One of a list · Default: 0 · Choices: , Off, 2048, 2 GB, 4096, 4 GB, 6144, 6 GB

donor-pool-mb = 
early-pool-above On/off

[early-pool] when the run directly above the window is shorter than 256MB because a mapping was already there before this constructor (Sentry 8A, iOS 27: a VM tag 1 malloc region at 0x14bd00000, the pool SHRINKING from 1152MB to 592MB), ...

Type: On/off · Default: 1

early-pool-above = 1
env.MADEIRA_ALIAS_PER_PROCESS Text

Default on. 0 restores the old pushes: every image goes to the emulator that registered last, and a registration drains every process's images.

Type: Text

env.MADEIRA_ALIAS_PER_PROCESS = value
env.MADEIRA_ALIAS_RELEASE On/off

Drop a released arena's code copies

Default off. 1: anonymous memory the game made executable (copied into the JIT pool) follows the game's MEM_RELEASE and MEM_DECOMMIT: a released view drops its copies' records, a decommit zeroes each copy in its pool slot. For a game that releases a memory arena and reserves it again at the same base. Logged as [alias-release]. Read once per session.

Type: On/off · Default: 0

env.MADEIRA_ALIAS_RELEASE = 1
env.MADEIRA_APP_UCRT Text

No description written yet.

Type: Text

env.MADEIRA_APP_UCRT = value
env.MADEIRA_ARENA_GUARD Text

On by default. MADEIRA_ARENA_GUARD=0 lets a fixed or hinted guest reservation take FEX arena space again.

Type: Text

env.MADEIRA_ARENA_GUARD = value
env.MADEIRA_AUX_IAT_HEAL Text

0: EC import stubs keep the exec-fault redirect

Type: Text

env.MADEIRA_AUX_IAT_HEAL = value
env.MADEIRA_CAGE_RELEASE Text

1: when the guest band is exhausted, hand the unclaimed 8 GB V8 cage holdback to it. Set by the app for a Madeira Dock session; off otherwise.

Type: Text

env.MADEIRA_CAGE_RELEASE = value
env.MADEIRA_CEF_CMDLINE On/off

Let in-process Chromium read the game's command line

1: in a program named by env.MADEIRA_CEF_PA_EXES, libcef.dll's cef_initialize clears the game's command_line_args_disabled, so Chromium switches given with env.MADEIRA_CHILD_ARGS (such as --single-process) reach it. For a game whose Chromium helper processes are refused memory (BeamNG.drive). Default off; set it in the game's own file; log [cef-cmdline].

Type: On/off · Default: 0

env.MADEIRA_CEF_CMDLINE = 1
env.MADEIRA_CEF_PA_EXES Text

Games that run Chromium in their own process

Exe names, separated by ';' (e.g. BeamNG.drive.x64.exe). A listed program gets the address space SocialClubHelper.exe gets under env.MADEIRA_SC_PA_POOLS: room for chrome_elf.dll's and libcef.dll's PartitionAlloc pools, Oilpan and V8's cage. Use it with env.MADEIRA_SC_PA_POOLS = 2 for a game that loads libcef.dll itself and stops in chrome_elf.dll (80000003). Empty by default; set it in the game's own file; read at session start.

Type: Text

env.MADEIRA_CEF_PA_EXES = value
env.MADEIRA_COW_OLD_PROT_RW Text

Windows reports a copy-on-write image page as read-write once it has been written (its private copy exists). Wine maps image pages writable from the start and cannot tell, so it always said WRITECOPY; V8 CHECKs that the flags pag...

Type: Text

env.MADEIRA_COW_OLD_PROT_RW = value
env.MADEIRA_CREATE_VIEW_REFUSE Text

Create a view. virtual_mutex must be held by caller. create-view refuse: a title died here 89 s in, while FEX started a thread and asked for 16 MB: "Assertion failed: (view->protect & VPROT_SYSTEM), function create_view", exit 0x80000101...

Type: Text

env.MADEIRA_CREATE_VIEW_REFUSE = value
env.MADEIRA_DECOMMIT_ZERO_PROT Text

[decommit-zero-prot] (Battle.net StarCraft menu freeze, iPad log b88b8e63): a COMMITTED guest page can still be host read-only (PAGE_READONLY, write-watch, guard, or a 4 KB neighbour on the same 16 KB host page). The memset below then fa...

Type: Text

env.MADEIRA_DECOMMIT_ZERO_PROT = value
env.MADEIRA_DEP_PER_PROCESS Text

(SetProcessDEPPolicy, permanent) therefore switched DEP back on for a running 32-bit game that had turned it off, and virtual_set_force_exec's sweep re-protected every view of every pseudo-process from the browser's thread: every executa...

Type: Text

env.MADEIRA_DEP_PER_PROCESS = value
env.MADEIRA_DETACHED Text

≤30min at 2s — covers the 20-min cap

Type: Text

env.MADEIRA_DETACHED = value
env.MADEIRA_DNSAPI_UNIXLIB Text

dnsapi's unix side is bound unless MADEIRA_DNSAPI_UNIXLIB=0, which keeps the stub table (every dnsapi unix call STATUS_NOT_SUPPORTED) as before.

Type: Text

env.MADEIRA_DNSAPI_UNIXLIB = value
env.MADEIRA_DONOR_BROWSERS On/off

Browsers take donor RAM

Off by default: memory of the Chromium browsers next to a game (Social Club's SocialClubHelper.exe, Steam's steamwebhelper.exe) is backed by the swap file, never by the donor pool. The pool is handed out by reserved size whether the pages are used or not, and Social Club's 4 GB allocator reservation used to take all of it before the game asked. 1: browsers take donor RAM like any program. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_DONOR_BROWSERS = 1
env.MADEIRA_DONOR_CHURN On/off

Short-lived memory takes donor RAM

On by default: memory a game frees and allocates again soon takes donor RAM while the pool has room, instead of counting against the app's memory limit. 0: it stays in the app's own memory as before. Read at session start.

Type: On/off · Default: 1

env.MADEIRA_DONOR_CHURN = 1
env.MADEIRA_DONOR_POOL_MARGIN_MB Text

Donor pool free-RAM margin (MB)

the donor pool takes no more memory while the host's free RAM is below this many MB. Off (0) since iOS keeps free RAM low on purpose, so 1024 and then 256 refused most takes on device; the memory-pressure notification alone guards. Set 256 to restore the old floor.

Type: Text

env.MADEIRA_DONOR_POOL_MARGIN_MB = value
env.MADEIRA_DONOR_WHOLE_MAX_MB Number

Largest reservation given donor RAM (MB)

0 (default): no limit. N: a reservation larger than N MB is backed by the swap file only, never by the donor pool (a test; a game's own big heap is usually hot and runs faster in donor RAM). Read at session start.

Type: Number · Default: 0

env.MADEIRA_DONOR_WHOLE_MAX_MB = 0
env.MADEIRA_DONOR_WINDOWS On/off

Donor pool: permanent region windows

1 maps every donated region into the address space when it is registered, as the first port did. Off (the default) maps only the range being freed, for its zeroing: the permanent windows were placed before Wine held the 32-bit guest-window slot and took it, so 32-bit programs failed at guest-window-reserve.

Type: On/off · Default: 0

env.MADEIRA_DONOR_WINDOWS = 1
env.MADEIRA_EA_CEF On/off

A store launcher's Chromium in one process

Default off; set with env.MADEIRA_SC_PA_POOLS = 2 for the EA app's launcher. EADesktop.exe runs --single-process with V8 --jitless (MADEIRA_JITLESS = 0 keeps V8's JIT), its --type= children are refused, and its four PartitionAlloc pools get the four 16 GB slots of the address band instead of overlapping. No effect on any other program.

Type: On/off · Default: 0

env.MADEIRA_EA_CEF = 1
env.MADEIRA_EA_CEF_CMDLINE On/off

Rewrite EADesktop.exe's command line

Default on. 0: while env.MADEIRA_EA_CEF is on, EADesktop.exe's command line is not rewritten; its --type= children are still refused. For testing a switch the launcher may not know.

Type: On/off · Default: 1

env.MADEIRA_EA_CEF_CMDLINE = 1
env.MADEIRA_EA_CEF_FLAGS Text

Extra EADesktop.exe switches

Appended verbatim to EADesktop.exe's command line while env.MADEIRA_EA_CEF is on (e.g. --disable-gpu).

Type: Text

env.MADEIRA_EA_CEF_FLAGS = value
env.MADEIRA_EXECREQ_LEAVE Text

Default off. 1 makes NtProtectVirtualMemory's [exec-req] path clear InSyscallCallback again, so the emulator hears about the memory changes that follow an executable protect on the same thread (GTA V Enhanced, the NoExec crash).

Type: Text

env.MADEIRA_EXECREQ_LEAVE = value
env.MADEIRA_EXE_WINDOW_HANDOFF Text

0 restores the old fixed-base handoff: claims are matched without rounding the image size to host pages, and a new main image never waits for the previous owner of the executable window to exit.

Type: Text

env.MADEIRA_EXE_WINDOW_HANDOFF = value
env.MADEIRA_EXE_WINDOW_SMALL_FIXED Text

0 keeps the executable window from a fixed-base (relocations stripped) image smaller than 64 MB, as before; such a program then fails to start.

Type: Text

env.MADEIRA_EXE_WINDOW_SMALL_FIXED = value
env.MADEIRA_EXE_WINDOW_WAIT_MS Text

how long a new main image with stripped relocations waits for the previous owner of the executable window to exit, in milliseconds; 0 does not wait

Type: Text

env.MADEIRA_EXE_WINDOW_WAIT_MS = value
env.MADEIRA_FEX_ARENA Text

Wine reserves a band; the emulator still runs its own selector and picks a different one. Holding 8GB therefore pushes it into whatever is left, and when that band is exhausted its 16MB requests fail, a thread-creation path dereferences ...

Type: Text

env.MADEIRA_FEX_ARENA = value
env.MADEIRA_FEX_ARENA_GROW Text

1: a full FEX arena adds a FEX_ONLY band below it (default off: on the Social Club layout a band lies in address space the browser helper's allocators were granted, and their writes corrupted it); default: the request fails as before

Type: Text

env.MADEIRA_FEX_ARENA_GROW = value
env.MADEIRA_FEX_BAND_KEEP_MB Number

Keep the lowest MB of the emulator's address range for the emulator

Default 0 (off). N MB: reservations of 32 MB to 1 GB that are placed above the game's own range because that range is tight may not take the lowest N MB of the emulator's 16 GB range; what no longer fits goes below it. For a game that reserves many 511 MB ranges and then ends with "FEXAlloc could not allocate"; 6144 keeps 6 GB. Only with the 16 GB range at 0x7c00000000. Logged as [fex-keep]. Read once per session.

Type: Number · Default: 0

env.MADEIRA_FEX_BAND_KEEP_MB = 0
env.MADEIRA_FEX_HEADROOM_LOG Text

0: no [fex-headroom] lines

Type: Text

env.MADEIRA_FEX_HEADROOM_LOG = value
env.MADEIRA_FIXED_BASE_GUARD On/off

Keep 0x140000000 for a fixed-base game

Default off. 1: a resource-only image view (a version or resource query, e.g. the Rockstar Games Launcher reading Social-Club-Setup.exe) never takes the reserved executable window at 0x140000000; it is mapped elsewhere. The window then stays free for a game exe without relocations that can only run there (Red Dead Redemption 2). It moves other programs' images too (GTA V Enhanced's, for one), so set it only in such a game's own file; read at session start.

Type: On/off · Default: 0

env.MADEIRA_FIXED_BASE_GUARD = 1
env.MADEIRA_FREE_DELAY_MS Text

How long a released 1-16 MB guest allocation stays mapped before it is really freed (default 0: freed at once; 2000 ms is the tested hold).

Type: Text

env.MADEIRA_FREE_DELAY_MS = value
env.MADEIRA_FREE_DELAY_REUSE Text

MADEIRA_FREE_DELAY_REUSE=0: a reservation over held releases fails until the delay runs out, as before; default 1: those held ranges are freed at once

Type: Text

env.MADEIRA_FREE_DELAY_REUSE = value
env.MADEIRA_GUEST_IMAGE_ANYWIN Text

wow-image-anywindow (Battle.net + Overwatch 2, bnettest16 log 41384ecd): the caller can be another process. Wine's virtual_enable_write_exceptions, run by the first x64 process, re-protects every view in the shared address space; on that...

Type: Text

env.MADEIRA_GUEST_IMAGE_ANYWIN = value
env.MADEIRA_GUEST_IMAGE_WRITE Text

memory is decided by its own rule (ios_guest_anon_rwx_is_host_data, below): a managed runtime's code buffers keep the pool alias and the store emulator, and those views are not SEC_IMAGE. The test is the view, not the address range. * vi...

Type: Text

env.MADEIRA_GUEST_IMAGE_WRITE = value
env.MADEIRA_GUEST_RWX_DATA Text

On by default: a guest's anonymous RWX data heap (Mono's Boehm GC) is plain read/write memory. 0 maps it through the JIT pool again, with every store emulated, as before.

Type: Text

env.MADEIRA_GUEST_RWX_DATA = value
env.MADEIRA_IAT_SYNC_KEEP Text

0 = the iat-sync translates unchanged file words too (old rule)

Type: Text

env.MADEIRA_IAT_SYNC_KEEP = value
env.MADEIRA_IMAGE_RELOAD Text

MADEIRA_IMAGE_RELOAD (default 1): 1 the same image reloaded at the same base by the same process gets its copy rebuilt in place (same pool address, fresh bytes, relocations and x18 patches redone); any other reuse of an unmapped copy get...

Type: Text

env.MADEIRA_IMAGE_RELOAD = value
env.MADEIRA_IMG_PROTECT_PROBE Text

MinHook/Detours, anti-cheat, Steam emulators) calls NtProtectVirtualMemory to make the code writable, then writes it. A 32-bit Black Ops II log (Sentry 7849899093) wrote two ntdll syscall stubs right after such a call and the page was st...

Type: Text

env.MADEIRA_IMG_PROTECT_PROBE = value
env.MADEIRA_JIT_ATTACH_CHECK On/off

0 treats JIT as ready whenever CS_DEBUGGED is set, as before, without asking whether a debugger is attached.

Type: On/off · Default: 1

env.MADEIRA_JIT_ATTACH_CHECK = 1
env.MADEIRA_JIT_IMAGE_RETIRE Text

new module runs the old module's translated code. Tombstone every pool mapping that overlaps the unmapped range before the VA can be reused, so the next image mapped there gets a fresh copy. The pool bytes themselves stay in the process ...

Type: Text

env.MADEIRA_JIT_IMAGE_RETIRE = value
env.MADEIRA_JIT_POOL_AUTO On/off

Bigger JIT pool for a game that ran out

Default on. A library game whose session logs [jit-pool] EXHAUSTED gets pool-split = 1 and env.MADEIRA_X64_IMAGE_NOCOPY = 1 added to its own config (a key it already sets, to any value, stays as it is), and the alert after the session asks for Madeira to be reopened, since the pool is set up once per app run. 0: nothing is added. Read when the pool runs out.

Type: On/off · Default: 1

env.MADEIRA_JIT_POOL_AUTO = 1
env.MADEIRA_JIT_POOL_NOTICE_NOW On/off

Say at once when a game ran out of JIT memory

Default on. When a library game's start runs out of JIT pool ([jit-pool] EXHAUSTED) while the starting screen is up, the screen says Not enough memory at once and offers Close Madeira; the next app run starts the game by itself. 0: the start waits for Steam's code 45 and the alert comes after the session, as before.

Type: On/off · Default: 1

env.MADEIRA_JIT_POOL_NOTICE_NOW = 1
env.MADEIRA_JIT_SMALL_NOTICE On/off

Banner when the JIT pool came out smaller

Default off. 1: once a game is up, a banner says JIT memory is small this time whenever iPadOS gave the pool less than asked (nearly every start without pool-split, and most games are fine). A start that really runs out says Not enough memory either way.

Type: On/off · Default: 0

env.MADEIRA_JIT_SMALL_NOTICE = 1
env.MADEIRA_JIT_TRAP_FALLBACK On/off

With no debugger attached, a JIT request fails the launch with a message; 0 lets it crash the app as before. CS_DEBUGGED stays set after a debugger detaches (JIT enabled by a tool that attaches and leaves, or without Madeira's script), a...

Type: On/off · Default: 1

env.MADEIRA_JIT_TRAP_FALLBACK = 1
env.MADEIRA_JUMBO_ALIGNED Text

0: a hinted reservation at a 4 GB boundary (V8's trusted range) takes a kernel pick as before, and furniture may fill the 4 GB-aligned gigabyte above a guest window (default 1: 4 GB-aligned bases are tried first and that gigabyte is left...

Type: Text

env.MADEIRA_JUMBO_ALIGNED = value
env.MADEIRA_JUMBO_HALF On/off

Give a too-large probe reservation half its size

Default off. 1: a reserve-only request of 4 GB or more (a power of two) that finds no hole gets half its size at a half-aligned free slot below the emulator's arena, for a game that finds each aligned arena with a double-size probe and keeps only half. A game that uses the whole reservation would fault, so set it per game. Logged as [jumbo-half].

Type: On/off · Default: 0

env.MADEIRA_JUMBO_HALF = 1
env.MADEIRA_KUSD_AVX Text

with MADEIRA_FEX_AVX=1 FEX runs AVX/AVX2 and its CPUID says so, but Wine fills the XSAVE configuration only on x86 hosts, so GetEnabledXStateFeatures still said "no AVX" and runtimes that ask it (.NET's JIT) kept AVX off. Describ...

Type: Text

env.MADEIRA_KUSD_AVX = value
env.MADEIRA_KUSD_CPU_COUNT Text

kusd-active-cpu-count: the [kusd-fill] path (madeira_kusd_fill_if_empty, from virtual_map_user_shared_data) runs before this process's PEB is set up, so peb->NumberOfProcessors is still 0 there and the shared page got ActiveProcessorCoun...

Type: Text

env.MADEIRA_KUSD_CPU_COUNT = value
env.MADEIRA_KUSD_FILL Text

iOS-Madeira [kusd-fill] (pending-prs/kusd-tick-multiplier, ported from wine unix/virtual.c to this file, which is what iOS builds): the static KUSER_SHARED_DATA fields (TickCountMultiplier, ActiveProcessorCount, NativeProcessorArchitectu...

Type: Text

env.MADEIRA_KUSD_FILL = value
env.MADEIRA_KUSER_VERSION Text

like a real Windows 10 workstation, with the same numbers init_peb() gives the PEB (OSMajorVersion 10, OSMinorVersion 0, OSBuildNumber 19045). Real Windows keeps the plain build number here; the 0xF0000000 "checked/free" flags exist only...

Type: Text

env.MADEIRA_KUSER_VERSION = value
env.MADEIRA_LAA Text

WHAT STAYS LOW regardless (unchanged by this policy, and deliberately so): the first TEB block and the PEB32/TEB32 derived from it (virtual_alloc_teb and the first-block allocation both hardcode limit_2g - 1), the KUSER_SHARED_DATA emula...

Type: Text

env.MADEIRA_LAA = value
env.MADEIRA_LAA_HIGH_IMAGES Text

No description written yet.

Type: Text

env.MADEIRA_LAA_HIGH_IMAGES = value
env.MADEIRA_LAA_LOWFIRST Text

No description written yet.

Type: Text

env.MADEIRA_LAA_LOWFIRST = value
env.MADEIRA_LAZY_PLACEHOLDERS Text

MADEIRA_LAZY_PLACEHOLDERS=0 reserves 64 MB to 1 GB placeholders whole again

Type: Text

env.MADEIRA_LAZY_PLACEHOLDERS = value
env.MADEIRA_LOW_ALLOC Text

a low pointer usable by other APIs. Handing a low address to the guest is therefore not viable without translating every API boundary that can receive a buffer pointer, which is a far larger surface than this experiment. * The machinery ...

Type: Text

env.MADEIRA_LOW_ALLOC = value
env.MADEIRA_MAP_RETRY_ANY Text

iOS: mach_vm_map can return KERN_INVALID_ADDRESS (→ ENOMEM) at certain addresses due to ASLR/system mappings. Keep scanning instead of aborting. ANY refusal means "not here, try the next spot" -- also the errno of an mmap over a ...

Type: Text

env.MADEIRA_MAP_RETRY_ANY = value
env.MADEIRA_MSM_CRASH_GUARD Text

No description written yet.

Type: Text

env.MADEIRA_MSM_CRASH_GUARD = value
env.MADEIRA_NO_GL Text

Real opengl32 unix side (OpenGL ES / desktop GL through the winios WGL driver). MADEIRA_NO_GL=1 keeps the old GL-absent stub table. The wow64 table's thunks convert every embedded guest pointer with ios_wow_host_ptr() (patches/wine-openg...

Type: Text

env.MADEIRA_NO_GL = value
env.MADEIRA_NO_HEAL_ESCALATE Text

.data GLOBAL, not an IAT — the IAT-restricted pass finds nothing and the same VA keeps costing one Mach exception per Metal call (118K+ observed; handler saturation = the desktop "freezes"). When the IAT pass strikes out, scan each copy'...

Type: Text

env.MADEIRA_NO_HEAL_ESCALATE = value
env.MADEIRA_NO_IMAGE_LOW_ALIAS Text

ios_lowalloc_translate, whole-span bounds-checked) instead. Registration refuses on collision with an image window, another alias, the arena or the bottom 16 MB, so it can never shadow a real name. * Scope: only images whose PREFER...

Type: Text

env.MADEIRA_NO_IMAGE_LOW_ALIAS = value
env.MADEIRA_NO_IMAGE_RETIRE Text

drops virtual_mutex before returning, so the interval is genuinely free for a moment and another thread may legitimately take it. That is reported as a named loss, never overwritten. * MADEIRA_NO_IMAGE_RETIRE=1 disables the handoff entir...

Type: Text

env.MADEIRA_NO_IMAGE_RETIRE = value
env.MADEIRA_NO_LOW_ALIAS Text

No description written yet.

Type: Text

env.MADEIRA_NO_LOW_ALIAS = value
env.MADEIRA_NO_PLAIN_EXEC Text

1: never ask mprotect for PROT_EXEC; every executable request takes the JIT-pool path, as on a TXM device. For iOS 18 and iOS 26 devices without TXM, where it would succeed in place. Default off: as before.

Type: Text

env.MADEIRA_NO_PLAIN_EXEC = value
env.MADEIRA_NO_QUERY_CLIP Text

min_address)) report MEM_RESERVE up to the floor; - otherwise ask the kernel where the next host mapping is. Host ranges inside a Wine reserved area stay free (map_fixed_area may overwrite them); any other host mapping ends the free regi...

Type: Text

env.MADEIRA_NO_QUERY_CLIP = value
env.MADEIRA_NO_SUBFLOOR_XQUERY Text

a window above 4GB (between it and the task's floor) is marked with bit 63, which no PE base carries, so FEX files it as a window, not as a JIT alias (IosJitAlias.cpp).

Type: Text

env.MADEIRA_NO_SUBFLOOR_XQUERY = value
env.MADEIRA_NTDLL_DATA_SYNC_RANGE On/off

ntdll data patches copy only the bytes asked for

Default off. 1: when a 64-bit game changes the protection of a few bytes of ntdll's writable data, only those bytes are copied to the copy ntdll runs from, not the whole page (which also overwrote live callbacks next to the slot). Logged as [ntdll-data-sync]. Read once per session.

Type: On/off · Default: 0

env.MADEIRA_NTDLL_DATA_SYNC_RANGE = 1
env.MADEIRA_PC2FH_OWN_SLOT Text

[pc2fh-slot] Where the trampoline lives. It is the same for every ntdll copy, so one copy of it sits in the last 64 bytes of the pool's reserved first page (IOS_JIT_PC2FH_SLOT_OFF), which is no image's alias: no guest protect, write or S...

Type: Text

env.MADEIRA_PC2FH_OWN_SLOT = value
env.MADEIRA_PIN_GRAPHICS_DLLS On/off

Keep graphics DLLs loaded

Default off. On a D3D12 device/probe call, pins already loaded D3D12, DXGI and Wine Metal DLLs until normal process shutdown, preventing repeated unload/reload copies. Keeps DLL data live; does not recycle executable ranges or change GPU capabilities. Restart the session after changing it.

Type: On/off · Default: 0

env.MADEIRA_PIN_GRAPHICS_DLLS = 1
env.MADEIRA_PLACE_PROOF Text

0 walks the whole map on every failed large mapping; by default a failed walk is trusted for 2 s until a release.

Type: Text

env.MADEIRA_PLACE_PROOF = value
env.MADEIRA_POOL_BIG_MAX Text

Optional bound on FEX code buffers over 16 MB that are live at once (MADEIRA_POOL_BIG_MAX=<1..16>, unset or 0: no bound, the old behaviour). ios_pool_code_cap() grants a 128 MB buffer to ANY process while 128 MB of room remain, so Battle...

Type: Text

env.MADEIRA_POOL_BIG_MAX = value
env.MADEIRA_POOL_BIG_SLOT_BELOW Text

1 puts the existing image slot below the native hole; 0/default keeps it above.

Type: Text

env.MADEIRA_POOL_BIG_SLOT_BELOW = value
env.MADEIRA_POOL_BIG_SLOT_MB Text

N MB adjacent to a split-pool hole for one image of 64 MB or more (Social Club's libcef.dll); off by default.

Type: Text

env.MADEIRA_POOL_BIG_SLOT_MB = value
env.MADEIRA_POOL_CODE_DEFER_FREE Text

0: a FEX code buffer released while a thread runs in it is refused and stays live, as before

Type: Text

env.MADEIRA_POOL_CODE_DEFER_FREE = value
env.MADEIRA_POOL_CODE_EXIT_RECLAIM On/off

Return an exited program's code buffers

On by default. When a program of the session exits (a launcher restarting itself, RockstarService.exe, a setup step), the emulator's code buffers it held go back to the JIT pool: reusable 3 seconds later, once no thread runs in them. Before, they stayed in use until Madeira closed, and a game started after many such exits got 16 MB code buffers and ran slowly. 0 keeps them in use, as before.

Type: On/off · Default: 1

env.MADEIRA_POOL_CODE_EXIT_RECLAIM = 1
env.MADEIRA_POOL_CODE_KEEP_BIG Text

0: a code buffer request takes the smallest free buffer that fits, however much larger, as before

Type: Text

env.MADEIRA_POOL_CODE_KEEP_BIG = value
env.MADEIRA_POOL_HEAD_RESERVE_MB Text

48 to 256 MB of image headroom in the FEX pool-tail budget; 48/default keeps the existing policy. Region C is unchanged.

Type: Text

env.MADEIRA_POOL_HEAD_RESERVE_MB = value
env.MADEIRA_POOL_LOW_IMAGES On/off

Small images in spare code-buffer space

Default off. If the normal JIT image allocation fails, copies up to 16 MB may use unallocated region C, preserving 4 MB for code buffers. Requires pool-low; 64-bit processes only. Does not shrink live buffers or the pool-low-margin.

Type: On/off · Default: 0

env.MADEIRA_POOL_LOW_IMAGES = 1
env.MADEIRA_POOL_QUARANTINE Text

OUT NON-EXEC off=0xa848000...). The next process started in that session (the windowed taskbar's in-session launcher: services.exe, then steam.exe) got its ntdll copy there and faulted NOEXEC at LdrInitializeThunk's first instruction, fo...

Type: Text

env.MADEIRA_POOL_QUARANTINE = value
env.MADEIRA_POOL_RECYCLE_IMAGES On/off

Images in retired code-buffer space

Default off. If other image allocations fail, retired region-C code buffers up to 64 MB may enter the image freelist after a 3-second grace, executable-page and thread-PC checks. Requires pool-low; 64-bit processes only. Live buffers and the pool-low-margin stay unchanged.

Type: On/off · Default: 0

env.MADEIRA_POOL_RECYCLE_IMAGES = 1
env.MADEIRA_POOL_SECTION_CLAMP Text

EXECUTE from max_protection for good , so every later hand-out there was born non-executable: device logs 80-83 show [pool-poison] starting exactly at such an image's allocation end, after which every process started later in the ...

Type: Text

env.MADEIRA_POOL_SECTION_CLAMP = value
env.MADEIRA_POOL_TAIL_FOR_HEAD Text

tail_resv: it is NOT lowered when the carve goes to the freelist. The counter is a plain byte count from the pool top; a carve in the middle cannot lower it without leaving a hole, and with pool-split a carve's grant can include spans it...

Type: Text

env.MADEIRA_POOL_TAIL_FOR_HEAD = value
env.MADEIRA_PRELOAD_DLLS Text

Load these DLLs with the D3D12 device

Default empty. DLL names separated by ';' (e.g. xinput1_4.dll): each program loads and pins them at its first D3D12 device or probe call, while the JIT pool still has room for their copies. RDR2 loads xinput1_4.dll only at its first controller read, and on build 476 the pool was full by then: no controller and no on-screen controls. Restart the session after changing it.

Type: Text

env.MADEIRA_PRELOAD_DLLS = value
env.MADEIRA_RDR2_VA_HOLD On/off

Keep 8960 MB free for Red Dead Redemption 2

Default off; only with env.MADEIRA_SC_PA_POOLS = 2. 1: Social Club's layout 2 keeps libcef.dll's PartitionAlloc pools at 256 MB and its metadata at 1 GB, chrome_elf.dll's metadata at 6.25 GB, gives the rest of the app's 4 GB hold to Wine's furniture (3.75 GB more room for threads and allocations), keeps Oilpan's cage at 1 GB so the FEX arena grows to 15 GB, and holds [0x75d0000000, 0x7800000000) from boot for one 8960 MB reserve, the one Red Dead Redemption 2 makes as it starts. Set it only in that game's own file; GTA V keeps layout 2 as it is. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_RDR2_VA_HOLD = 1
env.MADEIRA_REPLY_OWN_WRITABLE On/off

Server replies: a writable page is written in place

on (default): a server reply whose buffer lies in the JIT pool's address range but on a page that is writable at its own address (a page the pool gave up, which the system reused for a thread stack) is stored there, not through the pool's RW alias, which has no mapping for it. Before, a child process could die in its first reply (log 111: rpcss.exe, and the Steam client waited for it forever). 0: the pool's address range alone decides, as before.

Type: On/off · Default: 1

env.MADEIRA_REPLY_OWN_WRITABLE = 1
env.MADEIRA_RESERVED_REMAP On/off

Last resort for a refused window placement

Default on, and only on the path that already fails: when the system refuses every placement of a 32-bit program's request inside its 4 GB window (ENOMEM), the first refused range, which Wine's tables call free, is unmapped and mapped again without overwriting; if that fails the request fails as before. 0: no last resort. Read when a program starts.

Type: On/off · Default: 1

env.MADEIRA_RESERVED_REMAP = 1
env.MADEIRA_RESERVED_RETRY Text

So, on a small address map only (ios_wow_small_va_slots != 0, which is 0 on a 512 GB map) and only after the MAP_FIXED itself failed with ENOMEM, the next free range of the same area is tried, at most IOS_RESERVED_RETRY_MAX times, each o...

Type: Text

env.MADEIRA_RESERVED_RETRY = value
env.MADEIRA_RESOURCE_MAP_COPY Text

version queries and kept both copies until it exited; the pool ran out 1.4 s later. Set by virtual_map_section around the map, cleared by map_image_into_view for an image with a CLR header (CoreCLR maps its R2R assemblies this way and ru...

Type: Text

env.MADEIRA_RESOURCE_MAP_COPY = value
env.MADEIRA_RW_ALIAS_RETRY On/off

A process without the extended-virtual-addressing entitlement has a map that ends at 0xfc0000000 (63 GB). The 0x7000000000 hint is past its end, and an ANYWHERE search that starts past the end of the map does not wrap: every alias failed...

Type: On/off · Default: 1

env.MADEIRA_RW_ALIAS_RETRY = 1
env.MADEIRA_SAFE_IMAGE_READ Text

but names live in the image's read-only .rdata so they're stable. [stale-image] -- reads of a PE view that another thread (or this one) has just unmapped. * Wave 21, StarCraft from Battle.net, 19:07 log: tid 047c, inside mprotect_exec's ...

Type: Text

env.MADEIRA_SAFE_IMAGE_READ = value
env.MADEIRA_SC_GAME_CEF Text

env.MADEIRA_SC_GAME_CEF = 1 (experiment): the game keeps its libcef.dll. GTA log 2026-10-02 23:03 (file trace): GTA5_Enhanced.exe's socialclub.dll probes the Social Club files, loads libcef.dll -- refused here -- and later the helper con...

Type: Text

env.MADEIRA_SC_GAME_CEF = value
env.MADEIRA_SC_IPC_SPLIT Text

No description written yet.

Type: Text

env.MADEIRA_SC_IPC_SPLIT = value
env.MADEIRA_SC_PA_POOLS One of a list

Room for Social Club's PartitionAlloc pools

1: Wine boots with the emulator's arena at 0x7d00000000 (12 GB instead of 16 GB) and keeps 0x7c00000000 +4 GB free, so SocialClubHelper.exe's 32 GB PartitionAlloc reservation, which must start on a 32 GB boundary, gets 0x7800000000 (20 GB of it really reserved). 2: also libcef.dll's (0x7000000000) and Oilpan's; the JIT pool's RW alias moves to 0x7900000000. Off by default; set it in the game's own file; read at session start.

Type: One of a list · Choices: , Off, 1, Layout 1 (chrome_elf.dll only), 2, Layout 2 (chrome_elf, libcef, Oilpan)

env.MADEIRA_SC_PA_POOLS = 
env.MADEIRA_SC_RENDER_HANDLER Text

No description written yet.

Type: Text

env.MADEIRA_SC_RENDER_HANDLER = value
env.MADEIRA_SHARED_SECTION_EXEC Text

env.MADEIRA_SHARED_SECTION_EXEC = 1

Type: Text

env.MADEIRA_SHARED_SECTION_EXEC = value
env.MADEIRA_SHARED_SECTION_PRIVATE Text

0 fails the load of an image whose shared writable section is not aligned to the host page, as before; otherwise that section is mapped private.

Type: Text

env.MADEIRA_SHARED_SECTION_PRIVATE = value
env.MADEIRA_SHARE_PROBE Text

task #34 [share-probe]: DEFAULT-OFF (set MADEIRA_SHARE_PROBE=1). ml79: running it inline here (pre-detach, on explorer's boot thread) wedged the session — exec-at-alias hangs while the debugger is attached. Gated + deferred to a scratch ...

Type: Text

env.MADEIRA_SHARE_PROBE = value
env.MADEIRA_SHORT_MAP_ARENA_3GB Text

short-map-arena: on a 454 GB map (task ceiling between 64 GB and 496 GB) every step above 4 GB fails and the 4 GB step leaves only ~1 GB of the ~5 GB band for the guest (StS2 on iPhone19,4: its 895 MB image then fails to map). Working St...

Type: Text

env.MADEIRA_SHORT_MAP_ARENA_3GB = value
env.MADEIRA_SMALL_MAP_FIX Text

small-map-end: the walk can only over-read. When the probed top is well below it (iPad8,11 on iPadOS 26: walk 0x800000000, map end 0x458000000), use the probe: otherwise user_space_limit lies past the map and every top-down placement lan...

Type: Text

env.MADEIRA_SMALL_MAP_FIX = value
env.MADEIRA_SMALL_STACK_EXES Text

Programs whose threads keep a 2 MB stack

Empty by default: every thread stack is at least 8 MB (Chromium needs that). Exe names, separated by commas (e.g. RDR2.exe): threads of these programs get the stack they ask for, at least 2 MB, so their stacks take less of the shared memory space. Never list Chromium programs (SocialClubHelper.exe, Launcher.exe, steamwebhelper.exe). Read when a thread starts.

Type: Text

env.MADEIRA_SMALL_STACK_EXES = value
env.MADEIRA_STACK_OVERFLOW_EXIT Text

the whole pseudo-process ends, as on Windows (idea from the published patch 0058 of another iOS port). Ending only the thread left a half-dead process behind: a browser helper without its renderer thread stays up and is never res...

Type: Text

env.MADEIRA_STACK_OVERFLOW_EXIT = value
env.MADEIRA_SUBFLOOR_HIGH On/off

Images based just above 4 GB run through a window

on (default): a 64-bit exe or DLL without relocations whose base lies between 4 GB and the start of the app's address space (an old x64 linker's default 0x100000000, which iOS never maps) is mapped elsewhere, its header names the real base, and its own preferred-base addresses are served by the fault handler and FEX, as below 4 GB. The range is used only when a fixed allocation at its first and last page is refused as outside the map. Before, such an image failed to start (c0000018; log 115: the DirectX redistributable's x64 installer helper, so a game's first-run install script stopped). 0: the 4 GB limit, as before.

Type: On/off · Default: 1

env.MADEIRA_SUBFLOOR_HIGH = 1
env.MADEIRA_SUBFLOOR_LOWENTRY Text

0 = a fixed-base exe starts at its real (high) entry

Type: Text

env.MADEIRA_SUBFLOOR_LOWENTRY = value
env.MADEIRA_SUBFLOOR_SEH Text

0 = no unwind data for code at a fixed-base image's low addresses

Type: Text

env.MADEIRA_SUBFLOOR_SEH = value
env.MADEIRA_SUBFLOOR_VM Text

0 = VirtualProtect/VirtualQuery leave fixed-base image windows alone

Type: Text

env.MADEIRA_SUBFLOOR_VM = value
env.MADEIRA_SWAP_CHURN_TIGHT_MB Text

MB left before the app's memory limit below which churny sizes are tiered too (default 768, 0 = never)

Type: Text

env.MADEIRA_SWAP_CHURN_TIGHT_MB = value
env.MADEIRA_SWAP_COVERAGE One of a list

Swap tier coverage

Which allocations the swap tier backs with its file (only when the tier is on). Large allocations (classic, the default): single 8 MB+ commits in the guest band. All allocations of 1 MB+ (blocks). 1 MB+ and overflow (wide): blocks plus allocations outside the band and fresh reservations. Whole reservations 4 MB+ (broad, ): every new reservation of at least swap-min-mb (4 MB) below FEX's band backed whole when made, holes punched on decommit, swap-mb caps the disk it uses (a soft cap, checked when a block is backed). Unset: broad if swap-mode = 2, else classic.

Type: One of a list · Choices: , Large allocations (8 MB+), blocks, All allocations of 1 MB+, wide, 1 MB+ and overflow, broad, Whole reservations 4 MB+ (broad)

env.MADEIRA_SWAP_COVERAGE = 
env.MADEIRA_SWAP_DONOR_ONLY Text

the tier maps the donor pool only, no file

Type: Text

env.MADEIRA_SWAP_DONOR_ONLY = value
env.MADEIRA_SWAP_FILE Text

the tier maps the donor pool only, no file

Type: Text

env.MADEIRA_SWAP_FILE = value
env.MADEIRA_SWAP_HEAT Text

1: [swap] heat census of re-read swap extents; 2: plus new blocks of re-read sizes stay anonymous while the footprint has room; unset/0: off

Type: Text

env.MADEIRA_SWAP_HEAT = value
env.MADEIRA_SWAP_HEAT_FP_MB Text

swap-heat 2: the filter pauses while the footprint is at or above this (MB, 6656)

Type: Text

env.MADEIRA_SWAP_HEAT_FP_MB = value
env.MADEIRA_SWAP_HEAT_MIN Text

swap-heat 2: re-reads of a block size (in two extents or more) before its new blocks stay anonymous (6)

Type: Text

env.MADEIRA_SWAP_HEAT_MIN = value
env.MADEIRA_SWAP_MB Text

the tier maps the donor pool only, no file

Type: Text

env.MADEIRA_SWAP_MB = value
env.MADEIRA_SWAP_PUNCH_DEFER Text

MADEIRA_SWAP_PUNCH_DEFER=0 keeps every swap file punch synchronous, under the virtual lock.

Type: Text

env.MADEIRA_SWAP_PUNCH_DEFER = value
env.MADEIRA_SWAP_RESERVE_MAX_MB Number

Swap tier: largest reservation backed (MB)

The largest new reservation the swap tier backs whole: 256 MB in wide (at most 4 GB), 8 GB in broad (at most 16 GB). 9216 with broad coverage (swap-mode = 2) also backs Red Dead Redemption 2's 8960 MB heap with the file. Read at session start.

Type: Number

env.MADEIRA_SWAP_RESERVE_MAX_MB = value
env.MADEIRA_SWAP_TITLE_CHURN On/off

Short-lived memory of the game stays in RAM

On by default: a 64-bit game started beside 32-bit helpers keeps memory it frees and allocates again soon in RAM instead of the swap file, until less than MADEIRA_SWAP_CHURN_TIGHT_MB is left before the memory limit. 0: that memory goes to the donor pool or the swap file like the rest (slower once the device is out of free RAM). Read at session start.

Type: On/off · Default: 1

env.MADEIRA_SWAP_TITLE_CHURN = 1
env.MADEIRA_SWAP_X64_CHURN On/off

Swap tier: churn filter for 64-bit programs beside a 32-bit one

off (the default) sends a 64-bit program's short-lived allocation sizes to the swap file too while a 32-bit program is in the session, instead of leaving them anonymous (the churn filter): beside a 32-bit title the launcher chain is idle, and its anonymous pages were compressed into the footprint. 1 keeps the filter for them.

Type: On/off · Default: 0

env.MADEIRA_SWAP_X64_CHURN = 1
env.MADEIRA_SWAP_X64_TITLE Text

1 (the app): the session's title is 64-bit, its 32-bit programs helpers; donor RAM first beside them

Type: Text

env.MADEIRA_SWAP_X64_TITLE = value
env.MADEIRA_TAIL_CARVE_EXEC_CHECK On/off

Refuse a code buffer that cannot execute

Default on: a new emulator code buffer whose first 16 MB hold a JIT-pool page that lost execute permission for good is refused, and the emulator asks for half the size elsewhere. 0: every buffer is granted, as before. Read once per session.

Type: On/off · Default: 1

env.MADEIRA_TAIL_CARVE_EXEC_CHECK = 1
env.MADEIRA_THIN_RESERVE Text

1 unread, 0 off, 1 on

Type: Text

env.MADEIRA_THIN_RESERVE = value
env.MADEIRA_THIN_RESERVE_AFTER_GB Text

No description written yet.

Type: Text

env.MADEIRA_THIN_RESERVE_AFTER_GB = value
env.MADEIRA_THIN_RESERVE_MB Text

No description written yet.

Type: Text

env.MADEIRA_THIN_RESERVE_MB = value
env.MADEIRA_THREAD_STACK_SPILL On/off

New threads may use the kernel's pick when memory space is full

Default off. 1: a new thread's 1 MB kernel stack (and its emulator stack) is looked for from the start of Wine's furniture band instead of from 4 GB (each new thread no longer tries about 300 refused addresses first), and when that band is full the kernel places it anywhere still free instead of the thread failing. Red Dead Redemption 2 froze four minutes into the story because every new thread failed this way while 1.8 GB was free elsewhere. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_THREAD_STACK_SPILL = 1
env.MADEIRA_TOTAL_PHYS_MB Text

The limit is MEASURED, not assumed: os_proc_available_memory() is what remains before jetsam, and TASK_VM_INFO.phys_footprint is what is already charged, so their sum is this process's effective total. Cached on first use so the advertis...

Type: Text

env.MADEIRA_TOTAL_PHYS_MB = value
env.MADEIRA_USER_VA_GB Number

Address space the game is told it has (GiB)

Default 0 (off): a 64-bit game is told its user address space is what the device maps. N (4-4096, never more than the real figure): it is told N GiB; only the figure changes, not placement. For a game that sizes one reservation from it and quits when it cannot get it (32 is the value to try). Logged as [user-va]. Read once per session.

Type: Number · Default: 0

env.MADEIRA_USER_VA_GB = 0
env.MADEIRA_VALLOC_LOG_ALL Text

Bounded. A WoW64 process lives in its own 4 GB window, so every one of its allocations carries zero_bits and lands "above" its 32-bit limit by design; the uncapped branch below logged each of them: 127,000 lines (22 MB of a 25 MB device ...

Type: Text

env.MADEIRA_VALLOC_LOG_ALL = value
env.MADEIRA_VA_PRESSURE_GAP_OK On/off

A slow scan through the refused hole is not pressure

Default off. 1: an address-space scan that succeeded after grinding through the hole iOS refuses below the app image does not mark the address space as under pressure (which steers big reservations away from the swap tier). Read once.

Type: On/off · Default: 0

env.MADEIRA_VA_PRESSURE_GAP_OK = 1
env.MADEIRA_VA_SCAN_FLOOR Text

0: the free-area scan tries every granule below the address map's floor again (tens of thousands of refused mappings per placement) instead of jumping to the floor. Default on.

Type: Text

env.MADEIRA_VA_SCAN_FLOOR = value
env.MADEIRA_WARMER_SWEEP_CYCLES Text

cycles of ~2 s between the warmer's map walk and slot/window inventory (default 30; 5 = old).

Type: Text

env.MADEIRA_WARMER_SWEEP_CYCLES = value
env.MADEIRA_WG_64BIT Text

MADEIRA: winegstreamer's unix side is bound for 32-bit (wow64) callers, and for 64-bit (ARM64EC) ones too: without it an x64 program's xWMA voices (FAudio's WMA decoder DMO, wmadmod -> winegstreamer) decode to silence. A 64-bit caller ge...

Type: Text

env.MADEIRA_WG_64BIT = value
env.MADEIRA_WIDE_USER_VA Text

device. already applied exactly this reasoning to size the ARM64EC code bitmap ("nothing on iOS can be mapped at or above host_addr_space_limit"); this extends the same measured ceiling to what we tell applications. * Correct on bo...

Type: Text

env.MADEIRA_WIDE_USER_VA = value
env.MADEIRA_WIN32U Text

Register win32u's NtUser / NtGdi syscall table in slot 1. Activating this causes user32 process_attach to crash until wineserver shared-memory bringup is complete; gated on the MADEIRA_WIN32U env var so we can flip it on for debugging.

Type: Text

env.MADEIRA_WIN32U = value
env.MADEIRA_WOW64_BY_TEB Text

Guest windows are reserved lazily; this reserves nothing unless a 32-bit main image was published or MADEIRA_WOW_PLACEHOLDERS=1 (see ios_wow_session_start). Last, after the holdback, whose first page the lowest slot borrows as its guard.

Type: Text

env.MADEIRA_WOW64_BY_TEB = value
env.MADEIRA_WOW_AREA_BY_REQUEST On/off

32-bit windows: judge a merged area by the request

on (default): when two adjacent guest windows' reserved areas have merged into one (a slot carved from the holdback beside slot 0), a 32-bit process's allocation is judged by the window that holds its request. Before, the first window in the merged area decided, the second process was refused its own window and failed to create its TEB (every second concurrent 32-bit process of a session). 0: as before.

Type: On/off · Default: 1

env.MADEIRA_WOW_AREA_BY_REQUEST = 1
env.MADEIRA_WOW_ARENA_HOLD_GB Text

GB at the top of the FEX arena kept for a 32-bit program's emulator while MADEIRA_WOW_HOLD_WINDOWS is set (default 3); 0: none

Type: Text

env.MADEIRA_WOW_ARENA_HOLD_GB = value
env.MADEIRA_WOW_CHILD_WINDOW Text

wow-child-window: the owner fallback of ios_wow_slot_current() matches on the pthread_t that reserved the window. A slot that is already BOUND to a process has its owner thread long gone, and pthread_t values are recycled, so a new 32-bi...

Type: Text

env.MADEIRA_WOW_CHILD_WINDOW = value
env.MADEIRA_WOW_CPU_POOL_ONLY On/off

32-bit emulator module runs from its JIT-pool copy only

Default on. Where the kernel lets an image become executable in place (iOS 18; iOS 26 without TXM), the 32-bit emulator module (xtajit.dll) kept an executable view beside its JIT-pool copy, and its start-up code ran in the view while the emulator was called in the copy. On: EXEC is taken back from that view once the copy exists. 0: as before. Logged as [wow-cpu-pool]. Read once per session.

Type: On/off · Default: 1

env.MADEIRA_WOW_CPU_POOL_ONLY = 1
env.MADEIRA_WOW_EXTRA_WINDOW Text

A launcher -> helper -> program chain needs a THIRD window. After the carve, finish the held upper half of the cage, [0x7300000000, 0x73ffff0000), on demand. The missing 64 KB and the guard are acquired together with tryfixed, which refu...

Type: Text

env.MADEIRA_WOW_EXTRA_WINDOW = value
env.MADEIRA_WOW_FEX_BAND Text

madeira-bcd [wow-band]: the WOW64 CPU module (xtajit.dll) is never handed the arena (its ios_get_fex_arena unix call is unsupported), so its rpmalloc band selector asks for the whole hardware FEX band [0x7c00000000, 0x7fffffffff]. With e...

Type: Text

env.MADEIRA_WOW_FEX_BAND = value
env.MADEIRA_WOW_GUARD_INSIDE Text

0: a 32-bit guest window reserves 4 GB plus a guard page above it, as before (default 1: the guard is the window's top page, so the 4 GB gap above stays 4 GB-aligned)

Type: Text

env.MADEIRA_WOW_GUARD_INSIDE = value
env.MADEIRA_WOW_HOLD_FOR Text

Windows folder whose 32-bit programs alone may adopt the MADEIRA_WOW_HOLD_WINDOWS placeholders (the app sets the Dock game's folder); unset: any 32-bit program may

Type: Text

env.MADEIRA_WOW_HOLD_FOR = value
env.MADEIRA_WOW_HOLD_WINDOWS Text

bytes at the top of the arena the ARM64EC module's requests leave alone, for a 32-bit program that starts later in the session: its WoW64 module asks for the hardware band and nothing else, so when the 64-bit launcher chain has f...

Type: Text

env.MADEIRA_WOW_HOLD_WINDOWS = value
env.MADEIRA_WOW_LIMIT_BY_WINDOW Text

Guest windows are reserved lazily; this reserves nothing unless a 32-bit main image was published or MADEIRA_WOW_PLACEHOLDERS=1 (see ios_wow_session_start). Last, after the holdback, whose first page the lowest slot borrows as its guard.

Type: Text

env.MADEIRA_WOW_LIMIT_BY_WINDOW = value
env.MADEIRA_WOW_LIVE_WINDOW_GUARD Text

Worker threads of the exited process can stay asleep long after its main thread is gone; their TEBs are inside the window. Keep it (the next process takes another slot) while any of them still exists. MADEIRA_WOW_LIVE_WINDOW_GUARD=0 disa...

Type: Text

env.MADEIRA_WOW_LIVE_WINDOW_GUARD = value
env.MADEIRA_WOW_PRESSURE_RELEASE_MB Text

MB: when the 32-bit band has less free address space than this, idle 32-bit window placeholders are handed back (default 256); 0: never

Type: Text

env.MADEIRA_WOW_PRESSURE_RELEASE_MB = value
env.MADEIRA_WOW_RWX_PLAIN Text

Unset: a 32-bit window's anonymous RWX memory is plain read/write to the host once Wine Mono's libmono-2.0-x86.dll is mapped there (/). 1: in every 32-bit window. 0: never (stores go through the JIT pool's alias, and FEX's Mono bridge stays off).

Type: Text

env.MADEIRA_WOW_RWX_PLAIN = value
env.MADEIRA_WOW_SPILL_CEF Text

Still nothing: a 32-bit client with several 32-bit helpers can need more windows than the band holds. [0x7400000000, 0x7c00000000) is kept for a 64-bit Chromium's PartitionAlloc pools, which a 32-bit client does not use. Spill into it to...

Type: Text

env.MADEIRA_WOW_SPILL_CEF = value
env.MADEIRA_WOW_STACK_FREE_OWNER Text

process's window and released that process's live memory. Device log 95: a game creating and ending a short-lived thread in a loop while the Steam client started beside it lost guest 0x167e0000+0x10000 ("NO wine view", then a read access...

Type: Text

env.MADEIRA_WOW_STACK_FREE_OWNER = value
env.MADEIRA_WOW_STRICT_LIMITS Text

No description written yet.

Type: Text

env.MADEIRA_WOW_STRICT_LIMITS = value
env.MADEIRA_WOW_WINDOW_KEEP Text

0: other programs' views may be placed inside a 32-bit guest window or its placeholder again (default 1: only the window's own process maps there)

Type: Text

env.MADEIRA_WOW_WINDOW_KEEP = value
env.MADEIRA_WSEX_MINCORE Text

1: QueryWorkingSetEx's Valid bit from mincore() (iOS has no /proc pagemap); unset/0: every page reads as not resident, as before

Type: Text

env.MADEIRA_WSEX_MINCORE = value
env.MADEIRA_X18_TRAMP_ALIGN On/off

x18 trampolines on their own page

1 (default): an image whose .data was shifted to a 16 KB page gets its x18 trampolines on the page after it, not on its last .data page (mapped without exec). 0: the old offsets.

Type: On/off · Default: 1

env.MADEIRA_X18_TRAMP_ALIGN = 1
env.MADEIRA_X64_CHILD_NO_WINDOW Text

reserved. The owner fallback covers the boot gap in which the window is already bound but the new process's TEB is not published yet, so ios_jit_current_peb() cannot resolve the PEB. owner is the owning process's own boot thread, so th...

Type: Text

env.MADEIRA_X64_CHILD_NO_WINDOW = value
env.MADEIRA_X64_IMAGE_NOCOPY On/off

Pure-x64 images without a JIT-pool copy

Default off. 1: an x64-only image (not ARM64EC hybrid, not a Wine builtin) in a 64-bit process is not copied into the JIT pool; the emulator runs its code from the loaded image, as 32-bit programs already do, and its executable protections are applied without EXEC. Frees the pool for hybrid DLL copies and code buffers. Hybrid images keep their copy. Set it in the game's own file; restart the session after changing it.

Type: On/off · Default: 0

env.MADEIRA_X64_IMAGE_NOCOPY = 1
env.MADEIRA_X64_IMAGE_NOCOPY_AUTO Text

pool held 416 MB, so the copy failed ([jit-pool] EXHAUSTED, c0000017) on the first launch; Madeira then added env.MADEIRA_X64_IMAGE_NOCOPY = 1 and the next launch ran. Same images, same pool, no copy needed. So when a pure-x64 image alon...

Type: Text

env.MADEIRA_X64_IMAGE_NOCOPY_AUTO = value
env.MADEIRA_X64_RWX_PLAIN Text

Unset: a 64-bit program's anonymous RWX memory is plain read/write to the host once Unity's mono-2.0-bdwgc.dll is mapped. 1: in every 64-bit process. 0: never (stores go through the JIT pool's alias).

Type: Text

env.MADEIRA_X64_RWX_PLAIN = value
exe-window-mb Number

Executable window size (MB)

The address range at 0x140000000 kept for a game exe without relocations, which can only run there. Unset: 128 MB, or for a Madeira Dock launch the size of the largest such exe in the game's folder (The Adventures of Elliot: 473 MB -> 480). The JIT pool then starts above it and is that much smaller, so a large one also needs env.MADEIRA_X64_IMAGE_NOCOPY = 1 and pool-split = 1. A number sets it (129 to 960); 128 or less keeps 128 MB. Read at launch, the game's own file wins.

Type: Number · Default: 128

exe-window-mb = 128
fft-arena-patch On/off

Final Fantasy Tactics - The Ivalice Chronicles: shrink its 64 GB arena to the real part of oversize-reserve-mb

Type: On/off · Default: 0

fft-arena-patch = 1
iat-noexec On/off

madeira.cfg iat-noexec = 1

Type: On/off · Default: 0

iat-noexec = 1
jumbo-keep-mb Number

the keep floor, same units. madeira.cfg jumbo-keep-mb = N

Type: Number · Default: 0

jumbo-keep-mb = 0
jumbo-mb Number

madeira.cfg jumbo-mb = N

Type: Number · Default: 0

jumbo-mb = 0
main-stack-move On/off

No description written yet.

Type: On/off · Default: 0

main-stack-move = 1
metal-validation On/off

Metal API validation for this launch (debug layer, reports instead of aborts).

Type: On/off · Default: 0

metal-validation = 1
oversize-reserve On/off

serve a reserve too big for the map in part (Game details > Large memory reservations)

Type: On/off · Default: 0

oversize-reserve = 1
oversize-reserve-mb Number

its real part (MB)

Type: Number · Default: 16384

oversize-reserve-mb = 16384
oversize-reserve-min-gb Number

the size from which a reserve counts as oversize. Default 64 GB. A game's own config can lower it with oversize-reserve-min-gb (never below 33, so Chromium's 16 and 32 GB pools stay on their own paths). Subliminal (UE5) asks for ...

Type: Number · Default: 64

oversize-reserve-min-gb = 64
pool Text

JIT pool size (MB)

madeira.cfg pool: the JIT pool size in MB (256 to 1152); wins over the size above. The game's own file wins over madeira.cfg, so a game can size the pool to fit a free run above its executable window and pair it with pool-low.

Type: Text

pool = value
pool-low On/off

JIT code buffers below the executable window

1: a free run below the 0x140000000 executable window (less pool-low-margin) becomes a third debugger region for the emulator's code buffers, so the whole JIT pool is left to DLL copies (GTA V: about 300 MB more). Needs the pool above the window; costs the region's size in memory. Off by default; read at launch, the game's own file wins.

Type: On/off · Default: 0

pool-low = 1
pool-low-margin Number

Code-buffer region: MB left free below the window

With pool-low on: how much of the free run below the executable window stays free for programs that load there (child processes' main executables). A run with a free run at least this large below it keeps none. 128 by default.

Type: Number · Default: 128

pool-low-margin = 128
pool-mid On/off

Split JIT pool: use the free run between the regions

With pool-split on: when another mapping sits between the pool's two regions and leaves a free run of 64 MB or more there, that run becomes a third debugger region in the same pool (RDR2 build 470: 604 MB pool, a 71 MB mapping and 213 MB free between the regions; the DLL copies ran out and the game failed with ERR_GFX_INIT). Only from what the two regions left of the pool size; costs that region's size in memory. Off by default (RDR2's list turns it on); read at launch, the game's own file wins.

Type: On/off · Default: 0

pool-mid = 1
pool-page-fit On/off

Fit split pool regions to memory pages

With pool-split on: fit regions A/B to 16 KB pages instead of 16 MB steps, retaining small remainders in free runs without increasing the requested pool budget. With pool-low on, also fit region C to pages while preserving pool-low-margin. Costs the additional pages in memory. Off by default; read at launch, the game's own file wins. Restart Madeira and enable JIT again after changing it.

Type: On/off · Default: 0

pool-page-fit = 1
pool-pair On/off

Split JIT pool: prefer two runs above the window

With pool-split on: the pool takes two runs above the 0x140000000 executable window when together they are larger than the single run it would get -- whether that run lies below the window, where the pool cannot split (GTA V: 368 + 320 MB instead of 464 MB), or is the higher of two runs above it (The Adventures of Elliot: 240 + 288 MB instead of 288 MB). Falls back to the single run if the placement misses. On by default; 0 turns it off. Read at launch, the game's own file wins.

Type: On/off · Default: 1

pool-pair = 1
pool-split On/off

Split JIT pool around the main thread's stack

1: when the pool would shrink below its size (pool, 896 MB by default) because the main thread's stack splits the only executable band, the free run above the stack becomes a second debugger region and both form one pool (about 880 MB instead of 560-630 MB). Costs the second region's size in memory. Off by default; read at launch, the game's own file wins.

Type: On/off · Default: 0

pool-split = 1
swap-images On/off

Swap tier: pure-x64 DLLs and programs in the file

Default off. 1: the sections of pure-x64 images (with env.MADEIRA_X64_IMAGE_NOCOPY = 1: libcef.dll, steamclient64.dll, launchers, the game exe) move to the swap tier's file once they are read, so they stop counting against the memory limit (iOS writes them back and may drop them). Needs swap-mb. Page edges shared with a neighbouring section stay in memory. Set it in the game's own file; read at session start.

Type: On/off · Default: 0

swap-images = 1
swap-mb One of a list

Swap tier size

Moves game data to a file on this device's storage when memory runs short, up to this size. Off by default; read at launch.

Type: One of a list · Default: 0 · Choices: , Off, 1024, 1 GB, 2048, 2 GB, 3072, 3 GB, 4096, 4 GB

swap-mb = 
swap-min-mb Number

Swap tier floor (MB)

The smallest allocation the swap tier backs : 8 MB in classic, 1 MB in blocks and wide, 4 MB in broad unless set. MADEIRA_SWAP_MIN_KB overrides it for blocks, wide and broad.

Type: Number · Default: 0

swap-min-mb = 0
swap-mode Number

Swap tier mode (2 = broad)

2 selects broad swap coverage when env.MADEIRA_SWAP_COVERAGE is unset; any other value, classic. The coverage key wins when set.

Type: Number · Default: 1

swap-mode = 1
swap-wow64 One of a list

Swap tier for 32-bit programs

what the tier may do with memory a 32-bit program commits (inside its WoW64 guest window). Unset: donor RAM only, the memory stays ordinary RAM when the pool has none; it never goes to the swap file, which paged a 32-bit title's heap in and out of flash and froze it for seconds at a time. 1: donor RAM, then the swap file, like 64-bit programs (the old behaviour). 2: never tiered. The 64-bit launcher and helpers next to it still use the pool and the file.

Type: One of a list · Default: 0 · Choices: , Donor RAM only (default), 1, Donor RAM, then the swap file, 2, Never tiered (RAM only)

swap-wow64 = 
swap-x64 One of a list

Swap tier: where 64-bit programs go first

the stage a 64-bit program's memory takes first; the other is the fallback. Unset: the swap file while a 32-bit program is in the session (a guest window held or in use), so the kernel can evict the launcher chain's idle pages and the donor pool stays for the 32-bit program, which may not use the file; donor RAM first otherwise. 1: donor RAM first, always (the old behaviour). 2: the swap file first, always.

Type: One of a list · Default: 0 · Choices: , File while a 32-bit program runs, else donor RAM, 1, Donor RAM first, 2, Swap file first

swap-x64 = 
totalphys Number

Reported physical memory (MB)

madeira.cfg totalphys = N

Type: Number · Default: 0

totalphys = 0
vmwatch Text

madeira.cfg vmwatch = 0x<hex>

Type: Text

vmwatch = value

Direct3D 12

addr-scan On/off

Quicker GPU-address lookups

Default on. Finding the buffer behind a GPU address (every vertex buffer, index buffer and root descriptor a game records) walks back only over entries that can still reach the address, instead of over every buffer within the largest buffer's size of it (124 MB in Horizon Zero Dawn). The same buffer is found. 0: the old walk. Read once per game start.

Type: On/off · Default: 1

addr-scan = 1
ags-rewrite Text

D3D12 AMD AGS 64-bit atomics rewrite

read once; madeira.cfg ags-rewrite = 0 turns the rewrite off.

Type: Text

ags-rewrite = value
async-present-ahead Number

bounded run-ahead. Present enqueues and returns; the application may start the next frame while the worker encodes this one, but no more than async-present-ahead presents (default 1) may be queued behind it.

Type: Number · Default: 1

async-present-ahead = 1
async-submit Number

D3D12 asynchronous submission

asynchronous submission

Type: Number · Default: 0

async-submit = 0
attachless-split Number

/ madeira-bcd skin-check: before the pass, its captures are blits madeira.cfg attachless-split = 1 gives every draw of an attachment-less pass its own encoder. On Apple GPUs the fragment work of consecutive draws in one...

Type: Number · Default: 0

attachless-split = 0
barrier-render Number

; madeira.cfg barrier-render = 1 closes the render pass too (Astra's conservative experiment)

Type: Number · Default: 0

barrier-render = 0
bc-footprint-align Number

fix: BC footprints in whole 4x4 blocks, as D3D12 reports them (Satisfactory / Unreal "Footprint.Width % Format.BlockSizeX" assert); 0 = the mip's texel size

Type: Number · Default: 1

bc-footprint-align = 1
capture-big Number

each) ate the whole budget in the first capture of a UE5 frame, so the G-buffer, lighting and final image were never written. Skip targets over 16 MB unless madeira.cfg capture-big = 1.

Type: Number · Default: 0

capture-big = 0
capture-cs Text

re-read every CAP, so the target can change between captures of one run

Type: Text

capture-cs = value
capture-cs-indirect Number

re-read every CAP, so the target can change between captures of one run

Type: Number · Default: 0

capture-cs-indirect = 0
capture-cs-max Number

re-read every CAP, so the target can change between captures of one run

Type: Number · Default: 12

capture-cs-max = 12
capture-ps Text

re-read every CAP, like capture-cs

Type: Text

capture-ps = value
capture-raw Number

madeira-bcd: contact sheets

Type: Number · Default: 0

capture-raw = 0
capture-uav Number

madeira-bcd: contact sheets

Type: Number · Default: 1

capture-uav = 1
cbv-snapshot Number

fix attempt: copy N bytes (1 = 4096) of every UPLOAD-heap root CBV at replay and bind the copy

Type: Number · Default: 0

cbv-snapshot = 0
clear-defer On/off

Clears wait for the pass that draws to their target

On by default. A whole render-target or depth-stencil clear becomes the clear the next render pass that draws to that target starts with: a clear no longer ends the pass in progress unless it is one of that pass's own targets, and needs no pass of its own (which wrote the whole target to memory and read it back later). A barrier or copy that names the cleared texture, or a pass or clear that uses it through another view, applies the clear first, so nothing sees it uncleared. 0: every clear ends the open pass and goes before the next pass on its own, as before. Read once per game start.

Type: On/off · Default: 1

clear-defer = 1
clear-rects On/off

Clear only the rectangles a game asks for

Default off: a render-target or depth-stencil clear with rectangles clears the whole view, as before. 1: only the rectangles are cleared, in a small pass of their own (as DXMT's D3D11 ClearView does); a rectangle that covers the view still clears it the fast way. Horizon Zero Dawn passes rectangles from its first gameplay frames.

Type: On/off · Default: 0

clear-rects = 1
cs-concurrent Number

madeira-duo cs-concurrent: D3D12 orders dispatches only at a UAV or transition barrier, and every barrier here ends the compute encoder (fence-chain 1..5; f6 keeps it open, so stays serial). Inside one encoder the dispatches are independ...

Type: Number · Default: 0

cs-concurrent = 0
cs-dump Number

No description written yet.

Type: Number · Default: 0

cs-dump = 0
cs-split Number

fix: 1 = every compute dispatch ends its compute encoder, so the next one waits on the encoder fence (FSR 3 black squares: ordering inside an encoder); 2 = only FidelityFX ('CS' entry) dispatches

Type: Number · Default: 0

cs-split = 0
d3d12-bc-decode Number

1: decode BC uploads (no native BC), 0: raw copies

Type: Number · Default: 1

d3d12-bc-decode = 1
d3d12-binding-tier Number

Reported resource binding tier

Default 2. 3: OPTIONS reports resource binding tier 3, as Apple's D3DMetal and vkd3d-proton do; a game can take another binding path for it. Anything else keeps tier 2. Read once per game start.

Type: Number · Default: 2

d3d12-binding-tier = 2
d3d12-caps-log Number

2: format queries too

Type: Number · Default: 1

d3d12-caps-log = 1
d3d12-core-dll Number

1: load d3d12core.dll (Agility SDK layout); >1: also its D3D12SDKVersion

Type: Number · Default: 0

d3d12-core-dll = 0
d3d12-fl-12-1 On/off

Claim feature level 12_1

Default off: 12_0 is the highest feature level the runtime claims. 1: 12_1, for a game that creates its device at 12_1 and stops when that is refused; OPTIONS still reports no conservative rasterization or ROVs. Read once per game start.

Type: On/off · Default: 0

d3d12-fl-12-1 = 1
d3d12-msaa8 Number

1: report 8x MSAA (rendered at 4x)

Type: Number · Default: 0

d3d12-msaa8 = 0
d3d12-pso-cached-blob On/off

Cached blob of a pipeline

Default off: ID3D12PipelineState::GetCachedBlob fails (E_NOTIMPL), as before. 1: it answers a 16-byte blob, for an engine that treats the failure as fatal. Creating a pipeline never reads a blob handed back. Read once per game start.

Type: On/off · Default: 0

d3d12-pso-cached-blob = 1
d3d12-raw-typed-views On/off

Raw buffer views readable as typed

Default off. 1: raw and structured buffer views also carry a texture-buffer view (R32, or RG32/RGBA32 for a structured SRV whose stride allows it), as native drivers and vkd3d-proton do, so a shader that reads one as Buffer<T> gets the data instead of zeros (vertices at the origin). Costs one Metal texture object per such view.

Type: On/off · Default: 0

d3d12-raw-typed-views = 1
d3d12-raytracing-tier Number

Experiment: report a ray-tracing tier

Experiment, default 0. 10 or 11 reports DXR tier 1.0 or 1.1 in OPTIONS5 although the runtime has no ray tracing (its calls stay unimplemented stubs, logged once). Only for finding out whether a game's device check wants it.

Type: Number · Default: 0

d3d12-raytracing-tier = 0
d3d12-reserved-max-mb Number

d3d12-tiled-resources: largest reserved resource backed in full, in MB (larger ones are refused with E_OUTOFMEMORY)

Type: Number · Default: 1024

d3d12-reserved-max-mb = 1024
d3d12-shader-pack On/off

D3D12 shader cache in two pack files

Off by default: one file per converted shader in Documents/shadercache, as before. 1: the converter keeps its DXBC and DXIL cache entries in two append-only files (shadercache/pack/dxbc.mdpk, dxil.mdpk); loose entries of earlier runs move in as games use them. Off again, the packs are not read: what moved into them converts again. Bounds: DXIL as env.MADEIRA_D3D12_DXIL_CACHE_MB (512 MB), DXBC 2 GB; a full pack starts over. Read once per app start; the game's own file wins.

Type: On/off · Default: 0

d3d12-shader-pack = 1
d3d12-sm-6-7 On/off

Report shader model 6.7

Default off: SHADER_MODEL reports up to 6.6. 1: up to 6.7, for a game that requires it; the converter may still refuse a 6.7 shader, which fails its pipeline like any other conversion failure. Read once per game start.

Type: On/off · Default: 0

d3d12-sm-6-7 = 1
d3d12-tile-based Number

0: TileBasedRenderer FALSE, as desktop GPUs report

Type: Number · Default: 1

d3d12-tile-based = 1
d3d12-tiled-resources Number

opt-in: TiledResourcesTier 2, 40 VA bits per resource, R32G32B32 vertex formats, fully backed reserved resources

Type: Number · Default: 0

d3d12-tiled-resources = 0
d3d12-typed-uav-load Number

D3D12 typed UAV loads (report support)

FORMAT_SUPPORT below already reports UAV_TYPED_LOAD for every uncompressed colour format (Metal read-write textures), but this option stays FALSE by default: reporting it can move an engine that already runs onto different render...

Type: Number · Default: 0

d3d12-typed-uav-load = 0
d3d12-wave-ops On/off

Report wave operations

On by default. 0: OPTIONS1 reports WaveOps FALSE, so a game with a fallback picks shaders without wave intrinsics (an A/B for the shader converter's wave code; Horizon Zero Dawn reads it). Read once per game start.

Type: On/off · Default: 1

d3d12-wave-ops = 1
d3d12-zero-extent-guard Number

1 (default): zero-size textures refused with E_INVALIDARG; 0: passed to Metal, which aborts

Type: Number · Default: 1

d3d12-zero-extent-guard = 1
default-buffer-swap Number

fix: 1 = large committed DEFAULT buffers (no UAV/RT/DS) on file-backed storage, 2 = UAV ones too; 0 = Metal-owned private memory (as before)

Type: Number · Default: 0

default-buffer-swap = 0
default-buffer-swap-max-mb Number

default-buffer-swap moves buffers only while the moved total stays at or below this many MB; 0 = no limit

Type: Number · Default: 0

default-buffer-swap-max-mb = 0
default-buffer-swap-mb Number

fix: default-buffer-swap: the smallest DEFAULT buffer moved, in MB (at least 8)

Type: Number · Default: 64

default-buffer-swap-mb = 64
default-buffer-swap-wire Number

1 = VirtualLock (mlock) default-buffer-swap's storage so its pages stay resident; 0 = pageable (as before)

Type: Number · Default: 0

default-buffer-swap-wire = 0
desc-guard Number

diagnostic: log descriptor writes into shader-visible slots a running batch still uses

Type: Number · Default: 0

desc-guard = 0
draw-dedup On/off

Leave out render state the encoder already has

Default on. A draw no longer sends Metal the pipeline, viewport, scissor, depth-stencil state, blend colour, rasterizer state or buffer bindings the render encoder already holds from the draw before it; a buffer bound again with only a new offset is sent as an offset. Every draw still runs with exactly the state it set (about half of a Horizon Zero Dawn draw's Metal calls were such repeats). 0: every draw sends all of it, as before. Read once per game start.

Type: On/off · Default: 1

draw-dedup = 1
dump-shaders Text

madeira.cfg dump-shaders = mdc_x,mdc_y -> Documents/capture/shader_<name>.dxbc, written BEFORE the cache lookup so a cached shader is dumped too.

Type: Text

dump-shaders = value
dxbc-register-spaces On/off

Shader model 5.1 resources in register spaces other than 0

Default off: a DXBC shader (shader model 5.1) that declares a resource in a register space other than 0 is refused, and its pipeline is not created. 1: such shaders are converted, and each resource is bound from the root-signature entry with the same space and register. Horizon Zero Dawn needs it (its constant buffers sit in spaces 6 and 8). Shaders converted with it on are cached apart from the others. Read once per session.

Type: On/off · Default: 0

dxbc-register-spaces = 1
dxil-dump Text

diagnostic: log the bytecode of pipelines with these entry names

Type: Text

dxil-dump = value
dxil-tess Number

(IRRuntimeNewGeometryTessellationEmulationPipeline): the vertex shader becomes the object function with tessellation on, the hull shader two functions linked into it (hull and tessellator), the domain shader a function linked into the me...

Type: Number · Default: 1

dxil-tess = 1
dxil-tess-max-factor Number

particles through tessellated quads (ls_SetColor, max factor 9): 5,000-7,700 of them, drawn three times a frame, once the fires are going ([probe] log 2026-09-28 14:04) -- up to 162 triangles each through the emulation, and the GPU time ...

Type: Number · Default: 3

dxil-tess-max-factor = 3
dxil-tess-patch-topology On/off

Experiment: DXIL tessellation with the patch input topology

Experiment, default off. 1: the stages of a DXIL tessellation pipeline are converted with the converter's patch input topology instead of triangles; such shaders are cached apart.

Type: On/off · Default: 0

dxil-tess-patch-topology = 1
encode-batch On/off

One Metal call per encoder, not per draw

Default on. The commands a replay hands to one Metal encoder (every draw's state and draw, the encoder's fence wait and update) are queued and handed over in one call when the encoder ends, instead of one call into the Metal bridge per draw: the same commands in the same order, with ~1,500 fewer crossings a frame in Horizon Zero Dawn. 0: one call per draw, as before (for telling a regression apart on the device). Read once per game start.

Type: On/off · Default: 1

encode-batch = 1
encoder-labels Number

madeira.cfg encoder-labels = 1 names every Metal encoder after the pass that opened it ("R#<seq> <vs>|<ps>", "C#<seq> <kernel>", "B#<seq> copy"), so Instruments' Metal System Trace attributes GPU time per pass. Off by default: on...

Type: Number · Default: 0

encoder-labels = 0
env.MADEIRA_AGS_ROUNDTRIP_ONLY Text

0: shaders converted without D3D12's robust buffer access (bounds check), as env MADEIRA_IR_NO_BOUNDS_CHECK=1

Type: Text

env.MADEIRA_AGS_ROUNDTRIP_ONLY = value
env.MADEIRA_APP_IMAGE_UUID Text

set by the app: not a switch

Type: Text

env.MADEIRA_APP_IMAGE_UUID = value
env.MADEIRA_D3D12_CAPS_BY_FAMILY On/off

Report 64-bit atomics and wave operations by GPU

Default off: both are claimed on every GPU, as before. 1: 64-bit atomics (OPTIONS9, OPTIONS11) only on Apple9 GPUs (A17 Pro, A18, M3 and later) and wave operations (OPTIONS1) only from Apple7 (A14, M1), for an engine that picks shader paths the GPU cannot run.

Type: On/off · Default: 0

env.MADEIRA_D3D12_CAPS_BY_FAMILY = 1
env.MADEIRA_D3D12_CS_DUMP Text

400 files into C:\madeira-cs on every run cost startup time for a diagnostic that is only wanted while chasing one kernel.

Type: Text

env.MADEIRA_D3D12_CS_DUMP = value
env.MADEIRA_D3D12_DXIL_CACHE On/off

No description written yet.

Type: On/off

env.MADEIRA_D3D12_DXIL_CACHE = 1
env.MADEIRA_D3D12_DXIL_CACHE_MB Text

No description written yet.

Type: Text

env.MADEIRA_D3D12_DXIL_CACHE_MB = value
env.MADEIRA_D3D12_ONEPASS On/off

one conversion call instead of two. The size-then-fill protocol ran the whole compiler for the size query and again for the fill (the DXIL path had no cache to catch the second). A first buffer of four times the input plus 64 KB ...

Type: On/off

env.MADEIRA_D3D12_ONEPASS = 1
env.MADEIRA_D3D12_RS_DESERIALIZER Text

Read once. The switch exists so a device regression can be separated from this path without a rebuild.

Type: Text

env.MADEIRA_D3D12_RS_DESERIALIZER = value
env.MADEIRA_D3D12_TYPED_UAV_LOAD Text

FORMAT_SUPPORT below already reports UAV_TYPED_LOAD for every uncompressed colour format (Metal read-write textures), but this option stays FALSE by default: reporting it can move an engine that already runs onto different render...

Type: Text

env.MADEIRA_D3D12_TYPED_UAV_LOAD = value
env.MADEIRA_IR_NO_BOUNDS_CHECK Text

madeira-bcd: switches the converter service reads (madeira_ir_unix.mm, madeira_ags.cpp); set in madeira.cfg, as an env.NAME export there, or in the environment. "msc" = position invariance, strict NaN/Inf, sampler LOD bias (the MSC compa...

Type: Text

env.MADEIRA_IR_NO_BOUNDS_CHECK = value
env.MADEIRA_MSC_DYLIB Text

Host-only: lets the offline round-trip test point at the converter in the extracted package. Compiled out of the device build entirely, so the shipping runtime has exactly one place it will load the converter from.

Type: Text

env.MADEIRA_MSC_DYLIB = value
env.MADEIRA_PSO_ARCHIVE_INLINE On/off

Pipeline archive: compile once

With pso-archive on: 1 (default) compiles a pipeline the saved archive does not have once, into an open archive, and creates it from there. 0: created, then compiled again on one queue to be added (the first version; it kept about a quarter of a session's pipelines).

Type: On/off · Default: 1

env.MADEIRA_PSO_ARCHIVE_INLINE = 1
env.MADEIRA_PSO_ARCHIVE_MB Number

Pipeline archive: size cap (MB)

With pso-archive on: the most a game's pipeline archive folder keeps across builds. Over it, the oldest chunks are deleted at launch down to three quarters; a session adds none once it is reached.

Type: Number · Default: 1024

env.MADEIRA_PSO_ARCHIVE_MB = 1024
env.MADEIRA_PSO_ARCHIVE_PER_BUILD On/off

Pipeline archive: one per build

1: the archive folder sits in the build's shader cache directory and goes with it when a new build prunes it (the first version). Off: Madeira/PipelineArchive in LOCALAPPDATA, kept across builds.

Type: On/off · Default: 0

env.MADEIRA_PSO_ARCHIVE_PER_BUILD = 1
env.MADEIRA_X64_GRAPHICS_ENTRY On/off

Patchable x64 graphics method entries

Default off. 1 exposes typed x64 ARM64EC entries for swapchain Present/Present1, ResizeBuffers/ResizeBuffers1 and queue ExecuteCommandLists/GetTimestampFrequency/GetClockCalibration/GetDesc/Signal/Wait. With a DXMT dxgi that has the x64 entries, also selects the factory's patchable MakeWindowAssociation and swapchain-creation entries. The x64 entries use the loader's PE addresses so code patches and nearby allocations agree. Existing native implementations remain behind the entries. Restart the game session.

Type: On/off · Default: 0

env.MADEIRA_X64_GRAPHICS_ENTRY = 1
f6-compute-open Number

see f6_begin counts only madeira-bcd f6-rar

Type: Number · Default: 1

f6-compute-open = 1
f6-rar On/off

Experiment: fence-chain 6 ignores read-to-read barriers

Default off; only with fence-chain = 6. 1: a ResourceBarrier whose every transition goes from read states to read states (or is the first half of a split barrier) no longer makes the next GPU pass wait for all earlier ones, and no longer ends an overlapping render pass (which writes its targets to memory and reads them back). Direct3D 12 orders nothing at such a barrier; a game that relied on it anyway would show flicker. Read once per game start; [perf] f6-rar lines count them.

Type: On/off · Default: 0

f6-rar = 1
fence-chain Number

D3D12 fence chain mode

2 was clamped to 1 in -

Type: Number · Default: 1

fence-chain = 1
fence-early On/off

Fences advance when the GPU reached their batch

Default off. 1: a job whose command buffers have no query results advances its fence right after the GPU's shared event, and its buffers are retired in order on a second thread; under the CPU clamp the completion bookkeeping took 2-5 ms per job, which a game that polls its fences many times a frame waited for. Jobs with query results, a full ring or upload-guard take the old order. Read once per game start; [perf] fence-early lines show it.

Type: On/off · Default: 0

fence-early = 1
fence-poll-backoff Number

N >= 2 = a thread that polls one unchanged fence N times in a row (each within 50 us) sleeps until it moves, at most fence-poll-backoff-us; 0 = the locked read, as before

Type: Number · Default: 0

fence-poll-backoff = 0
fence-poll-backoff-us Number

fence-poll-backoff: the longest sleep in microseconds (20..2000), rounded up to whole milliseconds

Type: Number · Default: 200

fence-poll-backoff-us = 200
fence-strict Number

diagnostic: 1 = Queue::Wait waits for the commit and batches finish in serial order; 2 = also synchronous Signal and Present waits for its frame (slow)

Type: Number · Default: 0

fence-strict = 0
fi-field-check Number

diagnostic: every N presents (1 = 60) read back FSR 3's R32 vector fields before its Setup pass and after each later FidelityFX dispatch of that frame; log texels whose low half is a NaN/Inf half-float ([fi-field])

Type: Number · Default: 0

fi-field-check = 0
fi-nan-clean Number

fix: after each FidelityFX dispatch that binds one of the R32 vector fields FSR 3's Setup pass binds, a helper kernel zeroes the field's texels whose vector half (bits 0..15) is a NaN/Inf half-float (HFW's black squares); 2 = also when b...

Type: Number · Default: 0

fi-nan-clean = 0
fi-setup-zero Number

fix: zero-fill the R32 UAV textures of FSR 3's frame-interpolation Setup pass with a blit just before it (black squares: is Setup's own clear lost?)

Type: Number · Default: 0

fi-setup-zero = 0
fullscreen-window On/off

Full screen moves the game's window over the whole screen

Default off. 1: when a Direct3D 12 game switches to full screen, its window is moved to the screen's top-left corner and over the whole screen first, as Windows does; the game then sizes it to the chosen mode. Without it a game that only resizes its window (Red Dead Redemption 2) keeps it where it was, beside the Wine desktop. Read once per session.

Type: On/off · Default: 0

fullscreen-window = 1
gpu-fault-info Number

Batch command buffers are created with encoder execution status (madeira_ctl op 8, winemetal in DXMT), and a failed one logs its faulted encoders by label (op 9). After the first fault every encoder is labelled, a compute encoder runs ON...

Type: Number · Default: 1

gpu-fault-info = 1
gpu-fault-skip Number

No description written yet.

Type: Number · Default: 1

gpu-fault-skip = 1
gpu-sync Number

diagnostic: every ExecuteCommandLists commits its batch and waits until the GPU has finished it (no CPU/GPU overlap at all; slow)

Type: Number · Default: 0

gpu-sync = 0
gs-null-fragment On/off

Empty fragment function for pipelines without a pixel shader

Default on. Metal aborts on a mesh pipeline (geometry shader or tessellation emulation) with rasterization on and no fragment function, while D3D allows a pipeline with no pixel shader. On: such a pipeline gets an empty fragment function and writes no render target, as in D3D; depth and stencil work as before. Horizon Zero Dawn's pipeline thread died without it and the game stopped after its first frame. 0: such a pipeline is refused instead (the geometry shader is dropped). Pipelines with a pixel shader are not touched. Read once per session.

Type: On/off · Default: 1

gs-null-fragment = 1
heap-backing Number

No description written yet.

Type: Number · Default: 1

heap-backing = 1
ind-count Number

diagnostic: log N frames (1 = 3000) of per-pipeline ExecuteIndirect instance / threadgroup totals read back from the GPU; one-frame dips are flagged

Type: Number · Default: 0

ind-count = 0
ind-count-from Number

ind-count: the first present logged

Type: Number · Default: 0

ind-count-from = 0
ind-probe On/off

ExecuteIndirect probe (diagnostic)

Default on. Every 3 s per pipeline, the first argument record of an ExecuteIndirect is read back by a small compute pass and logged as a [probe] line, 1500 lines at most. Each probe ends the open render pass. 0: no probes (Red Dead Redemption 2's list, build 476).

Type: On/off · Default: 1

ind-probe = 1
indirect-fast On/off

Encode ExecuteIndirect records without per-record setup

Default off. 1: after the first record of an ExecuteIndirect, the other records (which share all state but their offset) are encoded 64 at a time with only their offset and the indirect draw or dispatch, instead of the whole per-draw setup each. For games that issue thousands of indirect records a frame (Red Dead Redemption 2), where that setup costs more CPU time than the GPU spends. DXIL and DXBC pipelines (DXBC from build 470); pipelines with tessellation or geometry stages, diagnostics and captures keep the per-record path. Read once per session.

Type: On/off · Default: 0

indirect-fast = 1
metalfx-upscale One of a list

MetalFX upscaling factor

Scales the presented picture with Apple's MetalFX spatial scaler (Direct3D 11 and 12). Usually set per game in Game details > Display.

Type: One of a list · Choices: , Off, 1.5, 1.5x, 2, 2x

metalfx-upscale = 
mip0-full Number

fix: a texture created with MipLevels 0 gets the full mip chain and GetDesc answers its count, as D3D12 does (FSR 3.1 frame generation's inpainting pyramid: Horizon Forbidden West's black squares); 0 = one level, GetDesc answers 0

Type: Number · Default: 0

mip0-full = 0
msc-bounds-check Number

0: shaders converted without D3D12's robust buffer access (bounds check), as env MADEIRA_IR_NO_BOUNDS_CHECK=1

Type: Number · Default: 1

msc-bounds-check = 1
msc-fail-memo On/off

Remember refused shaders for the session

Default off. 1: a shader the converter refused is not converted again for the next pipeline that uses it (same bytecode, root signature and options) until the game exits. Horizon Zero Dawn converted each refused shader ~6 times, ~30,000 conversions in its first minutes.

Type: On/off · Default: 0

msc-fail-memo = 1
msc-position-inf-nan Number

madeira-bcd: madeira_ir_unix.mm, build 217

Type: Number · Default: 1

msc-position-inf-nan = 1
msc-position-invariance Number

0: shaders converted without D3D12's robust buffer access (bounds check), as env MADEIRA_IR_NO_BOUNDS_CHECK=1

Type: Number · Default: 1

msc-position-invariance = 1
msc-sample-nan-zero Number

madeira-bcd: madeira_ir_unix.mm, build 217

Type: Number · Default: 1

msc-sample-nan-zero = 1
msc-sampler-lod-bias Number

0: shaders converted without D3D12's robust buffer access (bounds check), as env MADEIRA_IR_NO_BOUNDS_CHECK=1

Type: Number · Default: 1

msc-sampler-lod-bias = 1
msc-strict-nan Number

0: shaders converted without D3D12's robust buffer access (bounds check), as env MADEIRA_IR_NO_BOUNDS_CHECK=1

Type: Number · Default: 1

msc-strict-nan = 1
msc-unbounded-retry On/off

Retry refused shaders with sized unbounded ranges

Default off. 1: a DXIL shader the converter refuses with code 4 (a resource not in the root signature) is converted once more with the root signature's unbounded descriptor ranges given a size (2048 samplers, 1000000 others). Horizon Zero Dawn's ranges start at register 4 and ~4,900 of its shaders were refused. Once that works for a root signature, its later shaders take the sized ranges first.

Type: On/off · Default: 0

msc-unbounded-retry = 1
occlusion-visible Number

No description written yet.

Type: Number · Default: 0

occlusion-visible = 0
perf-log Number

where does the frame go? GPU busy (union of command-buffer GPU intervals), CPU time blocked in retire, presents -- logged every 5 s from Present. Off with madeira.cfg perf-log = 0.

Type: Number · Default: 1

perf-log = 1
present-min-ms Number

diagnostic: Present sleeps so that frames are at least N ms apart (200 = 5 fps), like the main menu's slow first seconds

Type: Number · Default: 0

present-min-ms = 0
pso-archive Number

compiled pipelines kept in Metal binary archives of our own (1; 0 = Metal's cache only)

Type: Number · Default: 0

pso-archive = 0
pso-async Number

madeira.cfg pso-async: 1 = a new render pipeline is built on a background thread and its draws are skipped until it is ready (no frame waits for the compiler); 0 = built at its first draw

Type: Number · Default: 0

pso-async = 0
pso-first-use Number

diagnostic: log every pipeline the first time a command list binds it, with the present it was created at

Type: Number · Default: 0

pso-first-use = 0
pso-lazy Number

madeira-bcd: madeira.cfg pso-lazy (default 1), see mad_pso_realize

Type: Number · Default: 1

pso-lazy = 1
pso-lazy-libs On/off

Shader libraries only for pipelines in use

Default off. 1: a pipeline built at its first draw (or dispatch) lets its converted Metal libraries go once the game has created it, and reads them back from the shader cache at that first draw. Horizon Zero Dawn creates ~52,000 pipelines in its menu and draws a few thousand; their libraries held hundreds of MB until iOS closed the game. Needs the shader cache (on by default); with pso-warm, a library stays until its warm-up compile is done.

Type: On/off · Default: 0

pso-lazy-libs = 1
pso-parallel Number

madeira.cfg pso-parallel (default 1): a batch's new pipelines built in parallel

Type: Number · Default: 1

pso-parallel = 1
pso-placeholder On/off

Placeholder for pipelines whose shaders did not convert

Default off. 1: a graphics pipeline whose vertex or pixel shader did not convert is returned to the game as a placeholder whose draws are skipped, instead of a failure. Horizon Zero Dawn stopped with an "Error" box when its settings menu got such a failure.

Type: On/off · Default: 0

pso-placeholder = 1
pso-share-libs Number

madeira.cfg pso-share-libs (default 1): identical converted libraries share one MTLLibrary. 0 keeps one per pipeline (the table is never trimmed, so this is the switch to compare memory with).

Type: Number · Default: 1

pso-share-libs = 1
query-timestamps On/off

Timestamp queries from the CPU clock

Default off: every timestamp resolves to zero. 1: a resolved timestamp is the process's monotonic clock in ns when the resolve is recorded (plus its place in the range), and GetClockCalibration's GPU value is the same clock, for a game that spins on zero timestamps. Nothing is measured on the GPU. Read once per game start.

Type: On/off · Default: 0

query-timestamps = 1
queue-trace Number

diagnostic: log the first N ExecuteCommandLists / Signal / Wait calls (1 = 400) with thread, queue type and fence state

Type: Number · Default: 0

queue-trace = 0
quiet-log On/off

Cheaper Direct3D 12 logging (no census frames)

1: the Direct3D 12 runtime's log lines skip OutputDebugString (an exception and a server request each, ~0.5 ms a line on the device) and reach the log through Wine's own debug output and stderr only; the census frames between presents 1500 and 3000 and the list 12000-12400 draw dumps are off (each froze the game for 1-2 s); the per-shader "converted at runtime" line is kept for the first 64 shaders and then every 1000th. A manual frame capture still works. Default off: the logging as before.

Type: On/off · Default: 0

quiet-log = 1
readback-far On/off

Experiment: empty culling readback

Default off. 1: a readback of a depth pyramid (an R32_FLOAT mip of 1 or more of a texture with 4+ mips, up to 64x64) is not copied; the CPU fills it with 4096, so a game that culls on the CPU against it culls nothing (everything is drawn: slower). A test, not a fix. Read once per game start.

Type: On/off · Default: 0

readback-far = 1
readback-swap On/off

D3D12 readback buffers on file-backed memory

Default on: like upload buffers (upload-swap), READBACK buffers of 8 MB or more live on file-backed storage, off the memory footprint. 0: READBACK buffers get Metal's own memory (Horizon Zero Dawn: two 32 MB buffers), so what the GPU writes into them reaches the CPU without the file tier between; upload buffers stay where upload-swap puts them. Read once per game start.

Type: On/off · Default: 1

readback-swap = 1
replay-split On/off

Log where Direct3D 12 submission time goes

Default off, logging only. 1: every 5 seconds a [perf] replay split line divides the time ExecuteCommandLists takes per frame into waiting for the queue, preparation, opening a command buffer, each kind of command (draws, dispatches, copies, clears, barriers, render targets, queries, state) and the end of each list. For finding why a game's frame is slow when the GPU is not busy.

Type: On/off · Default: 0

replay-split = 1
ring-share On/off

Share argument buffers between command lists

Default off. 1: a command list gives the argument-buffer chunks its replay wrote back as soon as the GPU is done with them, instead of keeping them until it is recorded again; all lists then share one pool. Red Dead Redemption 2 kept 1.5 GB of them (half of its Metal memory) with the switch off.

Type: On/off · Default: 0

ring-share = 1
rp-carry On/off

Experiment: render passes go on into the next command list

Default off. 1: when a command list ends inside a render pass and the next list of the same submission draws to the same targets first, with only state between the two draws, the pass stays open: its targets are not written to memory and read back. Horizon Zero Dawn records its depth and G-buffer passes in ~20 lists (0.3-0.6 GB a frame of such writes and reads), GTA V Enhanced its G-buffer in ~12. Opt-in: the second list's draws no longer wait for the whole first pass, an ordering Direct3D 12 does not promise but a game might rely on. Read once per game start; [perf] gpu-traffic lines show what it saves.

Type: On/off · Default: 0

rp-carry = 1
rp-discard On/off

Experiment: no load after, no store before DiscardResource

Default off. 1: after a game discards a whole render target or depth buffer (DiscardResource), the next render pass that draws to it does not read its old contents from memory, and a pass whose target is discarded (or cleared whole) next, before any other use in the same submission, does not write it back -- as tile-based GPUs do on Windows. Opt-in: a game that still reads what it discarded (desktop GPUs ignore discards) would show garbage there. Read once per game start; [perf] gpu-traffic lines show the bytes.

Type: On/off · Default: 0

rp-discard = 1
rp-lean On/off

Render passes fill only the targets they use

Default on. A Metal render pass is described with only the colour targets it uses; the bridge filled all eight slots for every pass (~240 Objective-C calls and 8 allocations a pass, a few hundred passes a frame). Metal ignores a slot without a texture, so the pass is the same. Also used by Direct3D 9/10/11 games through DXMT. 0: all eight slots, as before. Read once per game start.

Type: On/off · Default: 1

rp-lean = 1
sampler-census Number

diagnostic: log every distinct sampler filter value once with its Metal mapping

Type: Number · Default: 0

sampler-census = 0
shader-cache Number

No description written yet.

Type: Number · Default: 1

shader-cache = 1
shader-cache-native On/off

D3D12 shader cache files read natively

On by default. The Direct3D 12 runtime's shader cache (AppData\Local\Madeira\ShaderCache) is read and written by Madeira itself instead of through Wine's file calls, which asked Wine's server three times per entry (~3.5 ms each in Horizon Zero Dawn's menu, ~1,000 entries a second, with the server on a performance core). The same files either way. 0: Wine's file calls, as before. Read when the game creates its first pipeline.

Type: On/off · Default: 1

shader-cache-native = 1
skin-check Number

Diagnostic: check meshes skinned on the GPU

Default 0 (off). N: windows of N frames (1 = 8) log every draw that reads a vertex buffer a compute shader wrote, the dispatches that wrote it with every binding, a summary of up to 32 KB of each such stream copied just before the draw, and the shaders' bytecode. For characters drawn with missing faces or spikes (Horizon Zero Dawn); costs time in those frames.

Type: Number · Default: 0

skin-check = 0
skin-check-capture On/off

Diagnostic: skin-check copies the streams

On by default with skin-check. 0: log only, with no GPU copies, which add a copy between the skinning dispatches and the draw (to compare what the frames look like).

Type: On/off · Default: 1

skin-check-capture = 1
skin-check-every Number

Diagnostic: presents between skin-check windows

With skin-check on: a window starts this many presents after the previous one began (at least 30); the first starts 60 presents after the first such draw.

Type: Number · Default: 300

skin-check-every = 300
skin-check-trace On/off

Diagnostic: skin-check traces whole frames

Default off. 1, with skin-check on: the first frame of the first two windows logs every draw in one line (shaders, counts, streams, input layout); a pipeline with integer vertex inputs (a mesh skinned in its vertex shader) also gets its vertex-stage bindings, copies of its CPU-written inputs and first vertices, and its vertex shader's bytecode (32 such draws).

Type: On/off · Default: 0

skin-check-trace = 1
skin-dump On/off

Diagnostic: skin-check dumps the skinning data

Default off. 1, with skin-check on: in the first window's first two frames the compute shaders that skin a mesh have their inputs and the stream they wrote copied whole (up to 256 KB each) and logged as base64 (4 MB at most), so the skinning can be recomputed on a PC. Uses a 24 MB capture buffer.

Type: On/off · Default: 0

skin-dump = 1
skip-ps Text

diagnostic: drop the draws of these shader entries (comma list, exact names)

Type: Text

skip-ps = value
skip-ps-cycle Number

diagnostic: rotate skip-ps one name at a time, N seconds each (0 = skip all at once)

Type: Number · Default: 0

skip-ps-cycle = 0
sm5-flat-views Number

No description written yet.

Type: Number · Default: 1

sm5-flat-views = 1
static-cbv Number

Constant buffers as the draw was recorded

Default off: the GPU reads every descriptor of a table when it runs. 1: a descriptor table's single constant-buffer ranges are read when each draw or dispatch is recorded, as NVIDIA's driver and vkd3d-proton do; a game that rewrites one after recording the draw no longer makes that draw use another object's constants. Ranges marked VOLATILE stay as before. 2: VOLATILE ones too (vkd3d-proton's force_static_cbv). 3: only count the rewrites ([static-cbv] lines). Read once per game start.

Type: Number · Default: 0

static-cbv = 0
tv-hash Number

fix: typed-buffer views are found through a hash table once a resource has 32 of them, instead of a scan of all of its views under the device-wide view lock; 0 = the scan as before

Type: Number · Default: 1

tv-hash = 1
typed-uav-atomic Number

fix attempt: R32 UAV texture-buffer views (RWBuffer<uint>, UAV counters) get ShaderAtomic usage

Type: Number · Default: 0

typed-uav-atomic = 0
typed-view-align Number

Typed buffer view alignment

Default 0 (64 bytes, as before). 16 or 256: a typed buffer view's texture starts at that boundary, never below Metal's minimum for its format (logged once per format); 16 is what Apple's converter documents, so a float4 view has no padding elements. 4: every view's texture starts exactly at its first element, for the element sizes a GPU probe at the first view shows read right (logged); the others start at 16. A view Metal refuses there is made at 16, then 64. Read once per game start.

Type: Number · Default: 0

typed-view-align = 0
typed-view-rgb32 Number

fix: typed SRVs of UPLOAD memory in an R32G32B32 format (no Metal texture-buffer format) read a copy with 16-byte elements through an RGBA32 texture buffer

Type: Number · Default: 0

typed-view-rgb32 = 0
typed-view-shadow On/off

Aligned copies of offset typed views

Default off. 1: a typed shader-resource view of UPLOAD memory whose first element is not on a 16-byte boundary reads a 16-byte-aligned copy of its bytes, made when the view is made and refreshed at every ExecuteCommandLists (the GPU rounds a texture buffer's start down to 16 bytes and the shader converter ignores the element offset). view-census counts them. Read once per game start.

Type: On/off · Default: 0

typed-view-shadow = 1
upload-guard Number

diagnostic: 1 = log UPLOAD-heap data the game rewrites while the GPU still uses it; 2 = also compare with what the GPU read

Type: Number · Default: 0

upload-guard = 0
upload-guard-bytes Number

bytes upload-guard hashes per range (16..4096)

Type: Number · Default: 256

upload-guard-bytes = 256
upload-swap Number

D3D12 upload buffers on file-backed memory

madeira.cfg upload-swap (default 1)

Type: Number · Default: 1

upload-swap = 1
use-dedup Number

A draw's declarations count only once its chain has been encoded: a draw that returns early leaves them uncommitted, and the next begin drops them.

Type: Number · Default: 1

use-dedup = 1
view-census On/off

Diagnostic: report buffer views that fall back

Default off. 1: typed buffer views that cannot become a Metal texture buffer (the shader then sees no data), views cut short at the end of their resource, and views or constant buffer views past their resource are counted and named in the log, with Metal's minimum alignment for each pixel format typed views use. Changes nothing else.

Type: On/off · Default: 0

view-census = 1
vis-trace On/off

Diagnostic: per-frame draws and culling readback

Default off. 1: one log line per present (the HUD's frame number): draws, depth-only and 3+-target draws, indices, dispatches, depth-pyramid readback copies, new offset typed views, and Queue::Wait calls (how many passed before the awaited batch was committed); and every value of the 22x10, 11x5 and 5x2 mips of the pyramid a game culls with, as the GPU wrote them. The GPU also copies each of those mips into Madeira's own memory, and a mip whose readback memory holds something else is flagged (an earlier frame's values: STALE). Read once per game start.

Type: On/off · Default: 0

vis-trace = 1
vsps-fill Number

0: shaders converted without D3D12's robust buffer access (bounds check), as env MADEIRA_IR_NO_BOUNDS_CHECK=1

Type: Number · Default: 1

vsps-fill = 1
write-buffer-immediate On/off

WriteBufferImmediate writes its values

Default off: the method stays a stub (nothing written). 1: the values are written by the GPU in list order and a submission that wrote one is committed at once. CheckFeatureSupport still reports no support either way. Read once per game start.

Type: On/off · Default: 0

write-buffer-immediate = 1

App & front end

apicensus Text

top-level API census. Documents/madeira-apicensus.txt == "1" counts every call across the PE->unix winemetal boundary and classifies each as producer, consumer, lifetime, query, sync, presentation or bulk-memory. Needed because a ...

Type: Text

apicensus = value
arena Text

FEX arena placeholder. Documents/madeira-arena.txt == "1" makes Wine reserve FEX's host arena before any PE loads. OFF by default: FEX still selects its own band, and on hardware that band IS the reservation, so enabling it starve...

Type: Text

arena = value
arena-test Text

Arena carver self-test. Documents/madeira-arena-test.txt holds "churn:N", "ramp:N" or "random:N". Deliberately a SEPARATE file from madeira-arena.txt: a test that only runs when the feature is enabled cannot be used to decide whether to ...

Type: Text

arena-test = value
args Text

Stray (UE4). Launch the shipping binary DIRECTLY rather than Stray.exe -- the launcher builds its child's command line itself and passed only "Hk_project", so Unreal picked its default RHI. That default is DX12 for this title and ...

Type: Text

args = value
background-cpu Number

CPU cap in the background (% of one core)

While Madeira keeps a game or a download running in the background, its CPU use is held under this percent of one core on average (threads are paused for 100 ms at a time when it is over), because iOS ends a background app that averages more than about 80% for a minute. Higher loads faster but risks that. 0: no cap. A game's own config can set it. [bg-cpu] lines in the log.

Type: Number · Default: 50

background-cpu = 50
background-download Number

Keep downloads running in the background (minutes)

Minutes a Steam, Epic, GOG, EA or itch.io download keeps going after you switch apps or lock the screen. Then it pauses cleanly and continues when Madeira is active again. 0: only iOS's short grace period, as before.

Type: Number · Default: 60

background-download = 60
background-gpu-gate On/off

Hold GPU work in the background

On by default. While Madeira is not the active app, any thread other than the app's main thread that commits a Metal command buffer waits until Madeira is back, so a game that keeps loading in the background (Zink OpenGL, Direct3D, Vulkan) never sends GPU work iOS refuses and never loses its device. [metal-bg] lines in the log. 0: not installed. Read at app start.

Type: On/off · Default: 1

background-gpu-gate = 1
background-run Number

Keep a game running in the background (minutes)

Minutes a running game keeps going after you switch apps or lock the screen, so a long load finishes while you are away. Loading and other CPU work go on; drawing waits until Madeira is back (background-pause). The game's sound is muted meanwhile. 0: iOS pauses the game within seconds, as before. A game's own config can set it. [bg-run] lines in the log.

Type: Number · Default: 10

background-run = 10
background-sound On/off

Game sound in the background

Off by default: while a game keeps running in the background its sound is muted, and other apps' audio plays normally. 1: you keep hearing the game. A game's own config can set it.

Type: On/off · Default: 0

background-sound = 1
census Text

wmtcmd census. Documents/madeira-census.txt == "1" counts which of the 59 render/compute/blit command types a workload actually emits, and how large their sidecar data gets. Needed before serialising wmtcmd_* for the remote Metal ...

Type: Text

census = value
ctx-frame Text

syscall-frame context A/B. Documents/madeira-ctx-frame.txt == "1" makes ios_fill_thread_context() report a thread parked inside a syscall using its saved Wine syscall frame (TEB+0x378) instead of the Mach-O registers it happens to...

Type: Text

ctx-frame = value
d3d9 One of a list

Direct3D 9 frontend

Unset or "emulated": DXMT's D3D9 frontend, translated by FEX in 32-bit programs (x64 programs always get DXMT's native ARM64EC build). "native": 32-bit programs run DXMT's frontend as native ARM64 code. "wined3d": 32- and 64-bit programs get Wine's own d3d9 on wined3d's OpenGL renderer (opengl32 on Zink/MoltenVK; needs gl-backend = zink, the default when the bundle has gl/).

Type: One of a list · Choices: , Default (emulated), native, Native ARM64 frontend, wined3d, Wine wined3d on OpenGL (Zink)

d3d9 = 
desktop-size Text

Virtual desktop size (WxH)

The developer interface's Wine desktop size ; its Resolution menu writes it . Madeira Dock sessions without a game's Resolution use it too. Unset: this screen's shape at 1280x720's pixel count (1408x648 on a 19.5:9 iPhone, 1152x800 on an 11-inch iPad). Applies at the next app start.

Type: Text

desktop-size = value
dxmt Text

DXMT options (a=b;c=d)

Exported as DXMT_CONFIG with the options joined by ';', a library game's own dxmt options after these: e.g. d3d11.mipClampBC=1;d3d11.preferredMaxFrameRate=30. DXMT reads at most 259 characters of it, and nothing at all from a longer value .

Type: Text

dxmt = value
env.MADEIRA_ARGS Text

Optional MADEIRA_ARGS: Windows command-line quoting (CommandLineToArgvW rules), at most 64 arguments in 4 KB. Malformed or oversized input fails the launch instead of silently dropping or splitting arguments.

Type: Text

env.MADEIRA_ARGS = value
env.MADEIRA_AUDIO_IO_MS Text

A shared-mode client that keeps only one 10 ms engine period queued (IAudioClient3 low latency) loses audio when RemoteIO pulls a larger slice per callback (iOS's default is ~1024 frames, 21 ms): every callback empties the queue and play...

Type: Text

env.MADEIRA_AUDIO_IO_MS = value
env.MADEIRA_BATTLE_NET On/off

installed it downloads Blizzard's official installer into drive_c and adds it; once Battle.net is installed it adds Battle.net itself. Both get their recommended settings (GameRecommendations.battleNet / battleNetSetup): the Wine desktop...

Type: On/off · Default: 1

env.MADEIRA_BATTLE_NET = 1
env.MADEIRA_BUILD_LABEL On/off

Which build is installed, shown in light grey in the developer interface, and logged once at start ([build]). A build that writes MadeiraBuild into Info.plist (a round tag and build time) shows that; other builds show the bundle versio...

Type: On/off · Default: 1

env.MADEIRA_BUILD_LABEL = 1
env.MADEIRA_COMPAT_REPORT On/off

The Copy Compat Report button on a game's Advanced page (copies the Discord report format). 0 hides it.

Type: On/off · Default: 1

env.MADEIRA_COMPAT_REPORT = 1
env.MADEIRA_CONTROLS_EDITOR_DONE On/off

while editing, a Done button ends the edit (keeping it in the active custom layout) in place of the checkmark, and the show/hide glyph is hidden. MADEIRA_CONTROLS_EDITOR_DONE=0 restores the previous bar.

Type: On/off · Default: 1

env.MADEIRA_CONTROLS_EDITOR_DONE = 1
env.MADEIRA_DEBUG_VERBOSE Text

Wine trace channels. * 2026-05-19 perf pivot: the verbose default (err+all, fixme+all, warn+module, warn+file, trace+process, trace+module, trace+loaddll, trace+loadorder, trace+win, trace+user32, trace+syscall, trace+file) was generatin...

Type: Text

env.MADEIRA_DEBUG_VERBOSE = value
env.MADEIRA_DEVICE_STATS On/off

Opt-in (env.MADEIRA_DEVICE_STATS = 1): a line every 10 s during every session is a diagnostic, so it is off by default.

Type: On/off · Default: 0

env.MADEIRA_DEVICE_STATS = 1
env.MADEIRA_DOCK_CLEAR_STEAM_ID On/off

A Dock session publishes no fixed Steam game identity to its guests (WineProcessBridge.m): Valve's client runs in the host and gives each game its own. Every other launch clears the flag and is unchanged. env.MADEIRA_DOCK_CLEAR_STEAM_ID ...

Type: On/off · Default: 1

env.MADEIRA_DOCK_CLEAR_STEAM_ID = 1
env.MADEIRA_DOCK_GAME_SCM_FASTSYNC On/off

0: such a session runs Wine's standard sync, as before 2026-10-28

Type: On/off · Default: 1

env.MADEIRA_DOCK_GAME_SCM_FASTSYNC = 1
env.MADEIRA_DOCK_START_UNITY_DATA On/off

"Steam starts" (DockStartProgram): the chosen program takes the place of the one Steam's launch entry names, or the kept launcher goes back. No session runs.

Type: On/off · Default: 1

env.MADEIRA_DOCK_START_UNITY_DATA = 1
env.MADEIRA_DOCK_X64_TITLE On/off

0: a 32-bit helper in the game's folder keeps the 64-bit title's memory on the swap file first

Type: On/off · Default: 1

env.MADEIRA_DOCK_X64_TITLE = 1
env.MADEIRA_DOTNET10 On/off

.NET 10 runtime in Settings

Default on: Settings > Runtimes shows .NET 10 Desktop Runtime, which downloads Microsoft's .NET 10.0.9 x64 zips (base runtime + Windows Desktop runtime, size and SHA-512 pinned), and unpacks them into the prefix at C:\Program Files\dotnet\x64 for .NET 10 programs (Emuera). 0: the section is hidden. Logged as [dotnet10].

Type: On/off · Default: 1

env.MADEIRA_DOTNET10 = 1
env.MADEIRA_DXMT_EXTRA Text

madeira-bcd: the game's options from BCDLaunch.applyExtras (LibraryPrefs' NVIDIA device id), last, as before the merge. An option whose key is already set above is replaced, not repeated: DXMT reads at most 259 characters.

Type: Text

env.MADEIRA_DXMT_EXTRA = value
env.MADEIRA_EA On/off

Off with env.MADEIRA_EA = 0.

Type: On/off · Default: 1

env.MADEIRA_EA = 1
env.MADEIRA_ENV_LOCKED Text

madeira-env-locked: MADEIRA_ENV_LOCKED is a comma-separated list of names the host set on purpose. Without it a madeira.cfg line -- or a library game's own config -- could replace the program the front end was asked to launch, and the us...

Type: Text

env.MADEIRA_ENV_LOCKED = value
env.MADEIRA_EPIC On/off

Off with env.MADEIRA_EPIC = 0.

Type: On/off · Default: 1

env.MADEIRA_EPIC = 1
env.MADEIRA_EPIC_CLOUD On/off

Settings › Epic Games: whether saves sync, and whether this device's newer saves are sent without being asked. env.MADEIRA_EPIC_CLOUD = 0 turns the sync off; downloads and the comparison are on by default, uploading is not (`env.MADEIR...

Type: On/off · Default: 1

env.MADEIRA_EPIC_CLOUD = 1
env.MADEIRA_EPIC_CLOUD_AUTO_UPLOAD On/off

No description written yet.

Type: On/off · Default: 0

env.MADEIRA_EPIC_CLOUD_AUTO_UPLOAD = 1
env.MADEIRA_EPIC_LAUNCHER_PARENT On/off

Start Epic games under the Epic client's name

on (default): an Epic library game's x64 program starts as the child of C:\windows\system32\EpicGamesLauncher.exe (build/epic-parent: starts its command line, waits, returns its exit code; not the Epic client, no window, no network), as it does under the Epic client on Windows. A publisher's launcher that did not find a process with that name treated the Epic copy as not owned and showed its store page (testers' log, 2026-10-31: a publisher's launcher started by an Epic copy said 'Failed to relaunch from third party platform' and offered the game for sale; Heroic does the same for that launcher). A batch or a 32-bit program starts as before. 0: the program starts directly.

Type: On/off · Default: 1

env.MADEIRA_EPIC_LAUNCHER_PARENT = 1
env.MADEIRA_EXE Text

Program to start at launch (Windows path or name)

Pick which exe to run (env var override, default = cube.exe). Set MADEIRA_EXE=hello-x64.exe in env to launch the ARM64EC test path.

Type: Text

env.MADEIRA_EXE = value
env.MADEIRA_EXIT_REPORT On/off

Why a session ended by itself (not Quit): the program the app launched exited with a Windows error (wine_crash_exit_status, WineProcessBridge.m). MADEIRA_EXIT_REPORT=0 returns to the library without a message.

Type: On/off · Default: 1

env.MADEIRA_EXIT_REPORT = 1
env.MADEIRA_EXTERNAL_DISPLAY_FIX On/off

Without an external-display scene iOS only mirrors the phone, and the game's presenting layer (MetalHostView, a window-level CAMetalLayer view) did not come through mirroring: the TV stayed black or the game did not fill it. `env.MADEIRA...

Type: On/off · Default: 1

env.MADEIRA_EXTERNAL_DISPLAY_FIX = 1
env.MADEIRA_EXTERNAL_NESTED_LOG On/off

Log nested drive libraries

Drive libraries: the log names a Steam library that sits inside another listed library on the same drive (both are written to libraryfolders.vdf; Valve's client may keep only one; DJMAX RESPECT V code 41, Sentry Nov 16). Log only. 0 leaves the line out.

Type: On/off · Default: 1

env.MADEIRA_EXTERNAL_NESTED_LOG = 1
env.MADEIRA_EXTERNAL_PRUNE_PARENT_LIBRARIES On/off

Drive libraries: a leftover entry above a drive's Steam library (C:\External\steam when the games are in C:\External\steam\SteamLibrary) is removed from Steam's libraryfolders.vdf, so Valve's client lists the real library and Dock does n...

Type: On/off · Default: 1

env.MADEIRA_EXTERNAL_PRUNE_PARENT_LIBRARIES = 1
env.MADEIRA_EXTERNAL_STEAM_CONFIG_VDF On/off

Drive libraries: Madeira also lists them in Steam's config/libraryfolders.vdf (the file Valve's client reads), when it exists, beside steamapps/libraryfolders.vdf. 0 writes steamapps/ only.

Type: On/off · Default: 1

env.MADEIRA_EXTERNAL_STEAM_CONFIG_VDF = 1
env.MADEIRA_EXT_PROBE On/off

MADEIRA_EXT_PROBE=1: at session start the JIT helper extension reports the address space and memory limit its own process gets ( feasibility probe for extension processes)

Type: On/off · Default: 0

env.MADEIRA_EXT_PROBE = 1
env.MADEIRA_FAST_SERVER_START On/off

Wine starts as soon as the wineserver has finished starting up (its registry is loaded), normally within tens of milliseconds, instead of after a fixed 2 s pause. 0 restores the fixed pause.

Type: On/off · Default: 1

env.MADEIRA_FAST_SERVER_START = 1
env.MADEIRA_FRONTEND Text

Which interface Madeira starts with: the library (the default) or the developer interface. The choice is made in either interface, stored in UserDefaults and read once per run, so a change applies at the next start. Without a stored choi...

Type: Text

env.MADEIRA_FRONTEND = value
env.MADEIRA_FRONTEND_CONTROLLER On/off

The directions the left stick is pushed in now (with its in/out gap).

Type: On/off · Default: 1

env.MADEIRA_FRONTEND_CONTROLLER = 1
env.MADEIRA_FRONTEND_DEFAULT_NEW On/off

Which interface Madeira starts with: the library (the default) or the developer interface. The choice is made in either interface, stored in UserDefaults and read once per run, so a change applies at the next start. Without a stored choi...

Type: On/off · Default: 1

env.MADEIRA_FRONTEND_DEFAULT_NEW = 1
env.MADEIRA_FRONTEND_KEYBOARD On/off

MADEIRA_FRONTEND_KEYBOARD=0: the game view's own keyboard instead.

Type: On/off · Default: 1

env.MADEIRA_FRONTEND_KEYBOARD = 1
env.MADEIRA_GAME_CHILD_EXIT On/off

(game-child-exit) In a Madeira Dock or launcher session the program the app started (the Dock host, a launcher) is not the game: it ends with 0 while the game itself, a child process, crashed. The [game-end] line then said "exit code 0 (...

Type: On/off · Default: 1

env.MADEIRA_GAME_CHILD_EXIT = 1
env.MADEIRA_GESTURE_ZONES On/off

A swipe zone turns a swipe into a short press of one input per direction (D-pad by default), optionally limited to horizontal or vertical swipes, and a tap into another. - A look zone moves the mouse by the finger's motion, like a trackp...

Type: On/off · Default: 1

env.MADEIRA_GESTURE_ZONES = 1
env.MADEIRA_GET_HELP On/off

Get Help on a game's page and after a game stopped: sends the scrubbed report to Madeira's help server and shows its answer, with Apply and Undo for setting lines. 0 hides it.

Type: On/off · Default: 1

env.MADEIRA_GET_HELP = 1
env.MADEIRA_GET_HELP_OFFER On/off

The "<game> Stopped. Get Help?" offer in the library after a game stopped by itself or Madeira closed while it ran. 0 hides only the offer.

Type: On/off · Default: 1

env.MADEIRA_GET_HELP_OFFER = 1
env.MADEIRA_GL_EXTENSIONS_MAX Text

byte limit of GL_EXTENSIONS in 32-bit OpenGL contexts (opengl32, patches/wine-opengl-winios.patch): unset = 3072, 0 = none; d3d9 = wined3d makes it 0 unless set

Type: Text

env.MADEIRA_GL_EXTENSIONS_MAX = value
env.MADEIRA_GOG On/off

Off with env.MADEIRA_GOG = 0.

Type: On/off · Default: 1

env.MADEIRA_GOG = 1
env.MADEIRA_GOG_GALAXY On/off

GOG Galaxy's game services (sign-in, achievements, stats, leaderboards) for GOG games, answered by Madeira on 127.0.0.1:9977 while one runs (docs/GOG.md, "Galaxy"); 0 turns them off, in madeira.cfg or in one game's own config

Type: On/off · Default: 1

env.MADEIRA_GOG_GALAXY = 1
env.MADEIRA_GRAPHICS_SETTINGS On/off

0: no Settings › Graphics section; d3d9, d3d11, d3d12 and vulkan are back in All settings

Type: On/off · Default: 1

env.MADEIRA_GRAPHICS_SETTINGS = 1
env.MADEIRA_ITCH On/off

Off with env.MADEIRA_ITCH = 0.

Type: On/off · Default: 1

env.MADEIRA_ITCH = 1
env.MADEIRA_JIT_SHORTCUT On/off

Settings › JIT › Madeira JIT shortcut: when LocalDevVPN's loopback does not answer, Enable JIT runs the shortcut. Off unless it is 1.

Type: On/off · Default: 0

env.MADEIRA_JIT_SHORTCUT = 1
env.MADEIRA_JIT_SIGNING_CHECK On/off

Explains why JIT cannot be enabled on a copy signed without get-task-allow; 0 opens StikDebug regardless. A debugger can attach only to a process whose signature carries get-task-allow (a development signature). A copy signed with a dist...

Type: On/off · Default: 1

env.MADEIRA_JIT_SIGNING_CHECK = 1
env.MADEIRA_LANDSCAPE_ON_START On/off

(landscape-on-start) A game can switch the phone to landscape when it starts, and the phone goes back to turning freely when the game ends. The app asks iOS for the rotation (the supported-orientations mask plus a geometry update), which...

Type: On/off · Default: 1

env.MADEIRA_LANDSCAPE_ON_START = 1
env.MADEIRA_LAUNCH_EARLY On/off

0: Play keeps the Game details page up until the session begins

Type: On/off · Default: 1

env.MADEIRA_LAUNCH_EARLY = 1
env.MADEIRA_LAUNCH_FLOOD On/off

0: the starting screen fades in without growing out of the Play button

Type: On/off · Default: 1

env.MADEIRA_LAUNCH_FLOOD = 1
env.MADEIRA_LIBRARY_COVER_CACHE On/off

Library covers from the cover cache

On by default: the SwiftUI cards (list layouts, the original grid, the GOG, itch.io, Epic Games and EA sections) take their covers from the zoomable grid's cover cache: downsampled off the main thread, kept in memory and on disk, so a big library scrolls without covers popping in again. 0: AsyncImage, as before. Read at app start.

Type: On/off · Default: 1

env.MADEIRA_LIBRARY_COVER_CACHE = 1
env.MADEIRA_LIBRARY_HIDE_ENDED_DESKTOP On/off

whileClosing: Stop or Quit game went back to the library while Wine is still closing the session behind it, so the desktop is hidden without waiting for Wine.

Type: On/off · Default: 1

env.MADEIRA_LIBRARY_HIDE_ENDED_DESKTOP = 1
env.MADEIRA_LOG_COLLAPSE On/off

env.MADEIRA_LOG_COLLAPSE = 0 writes every repeated line again.

Type: On/off · Default: 1

env.MADEIRA_LOG_COLLAPSE = 1
env.MADEIRA_LOG_SUMMARY On/off

madeira-log-summary: the top of madeira-log.txt says what happened, before the full log. A fixed-size block (LogRuns.headerBytes) is the first thing in the file: the build, the device, madeira.cfg, and one line per game run (game, how lo...

Type: On/off · Default: 1

env.MADEIRA_LOG_SUMMARY = 1
env.MADEIRA_LOG_TICK On/off

(log-fixes) Wine, FEX and DXMT write into this file without a time. In each second that such lines arrive, one "[time]" line is written, so every one of them sits within about a second of a time (Sentry check Nov 9: 87-99% of a game's lo...

Type: On/off · Default: 1

env.MADEIRA_LOG_TICK = 1
env.MADEIRA_LOG_TRAIL On/off

[pad] a controller press while Madeira's menus own the pad, and where the ring went [focus] iOS's own focus moving (a controller or keyboard can drive it beside Madeira's) [screen] a named page or sheet opening or closing, and any alert ...

Type: On/off · Default: 1

env.MADEIRA_LOG_TRAIL = 1
env.MADEIRA_LOG_VIA_STDERR On/off

Once Wine points stderr at madeira-log.txt, the app's own log lines are written through stderr too (appendToFile); 0 keeps a per-call file handle.

Type: On/off · Default: 1

env.MADEIRA_LOG_VIA_STDERR = 1
env.MADEIRA_MENU_BLUR On/off

0: the in-game menu's solid panel, as before 2026-10-28

Type: On/off · Default: 1

env.MADEIRA_MENU_BLUR = 1
env.MADEIRA_NEW_LOOK_PAD On/off

X Play or Install on the highlighted game, else the layer's Play Y / View Search LB / RB the previous or next tab LT / RT a page up or down Menu the highlighted game's page (its settings) Layers: a screen or sheet over another one (the g...

Type: On/off · Default: 1

env.MADEIRA_NEW_LOOK_PAD = 1
env.MADEIRA_NO_STEAM_IDENTITY Text

set by the library for one launch of a game from another store; not a setting

Type: Text

env.MADEIRA_NO_STEAM_IDENTITY = value
env.MADEIRA_ONE_SESSION_PER_RUN On/off

One Wine session per app run (see LibraryModel.sessionsThisRun). First, so a start stopped from the starting screen, whose game may still be closing, says to restart.

Type: On/off · Default: 1

env.MADEIRA_ONE_SESSION_PER_RUN = 1
env.MADEIRA_PAD_OUTPUT_END On/off

a crashed game leaves the pad rumbling

Type: On/off · Default: 1

env.MADEIRA_PAD_OUTPUT_END = 1
env.MADEIRA_PANEL_IDLE On/off

hold the panel at 60 Hz under the 60 and 30 caps too. Without any display link a ProMotion iPhone lets the panel idle once nothing drives it: a 32-bit title under the 60 cap presented at a steady 9.9 FPS with the GPU 1% busy, eve...

Type: On/off · Default: 0

env.MADEIRA_PANEL_IDLE = 1
env.MADEIRA_PHONE_HOVER On/off

1: on iPhone, pointer interactions attach their drivers as on iPad, so hover from the AssistiveTouch cursor reaches the game view

Type: On/off · Default: 0

env.MADEIRA_PHONE_HOVER = 1
env.MADEIRA_PHONE_IPAD_IDIOM On/off

1: the app runs with the iPad interface idiom on iPhone, so pointer lock is requested (Madeira's screens use iPad layouts)

Type: On/off · Default: 0

env.MADEIRA_PHONE_IPAD_IDIOM = 1
env.MADEIRA_PLAIN_TIME On/off

[plain-time] HH:mm:ss in local time from localtime_r: a new DateFormatter per call crashed inside ICU (Sentry 9J/9N/AX/E3). Same text. Off: env.MADEIRA_PLAIN_TIME = 0.

Type: On/off · Default: 1

env.MADEIRA_PLAIN_TIME = 1
env.MADEIRA_PROFILE_LOCALLOW Text

0 leaves the profile's AppData\LocalLow folder missing, as before.

Type: Text

env.MADEIRA_PROFILE_LOCALLOW = value
env.MADEIRA_PROMOTE On/off

Hold the display at its maximum rate

The opt-in above; read when a session's pacing is applied.

Type: On/off · Default: 0

env.MADEIRA_PROMOTE = 1
env.MADEIRA_RUNTIME_SETTINGS On/off

The Display and Memory and sync settings pages.

Type: On/off · Default: 1

env.MADEIRA_RUNTIME_SETTINGS = 1
env.MADEIRA_SESSION_DIAGNOSTICS On/off

The in-game menu's Diagnostics (frame capture, GPU sync), for testing: off unless madeira.cfg sets env.MADEIRA_SESSION_DIAGNOSTICS = 1. A capture writes render-target pixels to Documents/capture, which Files shows.

Type: On/off · Default: 0

env.MADEIRA_SESSION_DIAGNOSTICS = 1
env.MADEIRA_SESSION_TOOLS On/off

The in-game Aspect & scaling choice sticks to the game. MADEIRA_SESSION_TOOLS=0 hides that picker and leaves the stored choice alone.

Type: On/off · Default: 1

env.MADEIRA_SESSION_TOOLS = 1
env.MADEIRA_SHARED_CONFIGS On/off

Shared settings from other players

Settings other players said work for a game, approved by Madeira, used as that game's recommended settings when it has no list of its own; Madeira asks Keep or Undo the first time. 0 turns it off. Read at app start.

Type: On/off · Default: 1

env.MADEIRA_SHARED_CONFIGS = 1
env.MADEIRA_SHORT_MAP_NOTICE On/off

short-map-notice: iOS gave this run a shorter address map than the usual 512 GB (454 GB on an iPhone19,4 in Nov 2026) and the start has failed. Big games (Slay the Spire 2, Tetris Effect, Mina the Hollower) failed on every launch in that...

Type: On/off · Default: 1

env.MADEIRA_SHORT_MAP_NOTICE = 1
env.MADEIRA_SIGNING_REFRESH On/off

Off by default: no Settings section, no refresh or offer over the library and no sign-in taken from an installer. A refresh asks Apple's portal for a profile on the Apple ID that signs other apps too, so the installer that signed Madeira...

Type: On/off · Default: 0

env.MADEIRA_SIGNING_REFRESH = 1
env.MADEIRA_STDIN_PIPE Text

env.MADEIRA_STDIN_PIPE = 1 puts a pipe on fd 0 so a guest can read stdin at all; without it fd 0 is whatever iOS gave us, which reads as immediate EOF. Off by default: an unread pipe fills at 64 KB and blocks the guest on its next write,...

Type: Text

env.MADEIRA_STDIN_PIPE = value
env.MADEIRA_STDOUT_PIPE Text

env.MADEIRA_STDOUT_PIPE = 1 moves the guest's stdout onto its own pipe, leaving fd 2 on madeira-log.txt. That is the seam the code already had: Wine's err:/warn: channels and every dprintf(STDERR_FILENO, ...) are stderr, the guest's prin...

Type: Text

env.MADEIRA_STDOUT_PIPE = value
env.MADEIRA_STEAM_APPID Text

set by the library for one direct Steam start (Start with: The game); not a setting

Type: Text

env.MADEIRA_STEAM_APPID = value
env.MADEIRA_STEAM_APPPATH Text

that game's install folder, with MADEIRA_STEAM_APPID; not a setting

Type: Text

env.MADEIRA_STEAM_APPPATH = value
env.MADEIRA_STEAM_FIXED_IDENTITY On/off

Give this game the fixed Steam identity

on (default): a game started outside Madeira Dock and not through Steam's "The game" start gets the bridge's fixed Steam identity (SteamAppId 356400, SteamGameId, SteamAppPath = Thumper's folder). A game with its own Steam wrapper then sees another title's app ID. Seasons after Fall quits by itself with exit code 0 after about 90 s with it (testers' logs, 2026-11-15). 0, in that game's own config: no Steam identity is published for this game.

Type: On/off · Default: 1

env.MADEIRA_STEAM_FIXED_IDENTITY = 1
env.MADEIRA_STEAM_NEEDED_HINT On/off

The program the library started ended while a steam.exe it started still ran, outside a Madeira Dock session: the game only runs when Steam starts it (SteamAPI_RestartAppIfNecessary). Slay the Spire 2 on "Start with: The game" does this....

Type: On/off · Default: 1

env.MADEIRA_STEAM_NEEDED_HINT = 1
env.MADEIRA_STORE_STEAM_IDENTITY On/off

Give games from other stores the fixed Steam identity

off (default): a game from another store (an Epic library entry) starts without the fixed Steam identity (SteamAppId, SteamGameId, SteamAppPath) every other launch outside Madeira Dock gets. With it, a game's launcher took its Steam path, its Steam API start failed and it showed only an error (testers' log, 2026-10-31: a publisher's launcher started by an Epic copy, 'Steam failed to initialize'). 1: publishes it as before.

Type: On/off · Default: 0

env.MADEIRA_STORE_STEAM_IDENTITY = 1
env.MADEIRA_THERMAL_CAP On/off

Opt-in env.MADEIRA_THERMAL_CAP = 1: when iOS reports the device as serious or critical, a session paced at the 60 cap, MAX or RAW drops to the 40 cap (three refreshes at 120 Hz, so evenly spaced; the 30 cap where 40 is not offered). A ...

Type: On/off · Default: 0

env.MADEIRA_THERMAL_CAP = 1
env.MADEIRA_TOUCH_KEY_MIN_HOLD_MS Text

The shortest press a touch key or mouse button sends: env.MADEIRA_TOUCH_KEY_MIN_HOLD_MS in milliseconds (0 to 500; a game's own config can set it), 60 ms by default, about two frames at 30 fps. 0: a release is sent the moment the finge...

Type: Text

env.MADEIRA_TOUCH_KEY_MIN_HOLD_MS = value
env.MADEIRA_TOUCH_MOUSE Text

1: touches always reach the program as a mouse, 0: never; default: not while touch controller mappings are shown

Type: Text

env.MADEIRA_TOUCH_MOUSE = value
env.MADEIRA_UI_LOG_IDLE On/off

Pending batched diffs to apply on main thread

Type: On/off · Default: 1

env.MADEIRA_UI_LOG_IDLE = 1
env.MADEIRA_UPLOAD_SLIM On/off

(log-fixes) env.MADEIRA_UPLOAD_SLIM = 0 sends every line of each log (LogSlim.swift).

Type: On/off · Default: 1

env.MADEIRA_UPLOAD_SLIM = 1
env.MADEIRA_USE_ARM64EC Text

Heuristic: x86_64 guest exes (cube-x64, hello-x64, real games like Thumper) need the arm64ec-windows bundle (ARM64EC hybrid system DLLs that interop with FEX-translated x86_64 code). ARM64-native tests (cube.exe) use the aarch64-windows ...

Type: Text

env.MADEIRA_USE_ARM64EC = value
env.MADEIRA_VCREDIST On/off

env.MADEIRA_VCREDIST = 0 (madeira.cfg or the environment) leaves the Visual C++ runtime installer out of setup and Settings. On by default.

Type: On/off · Default: 1

env.MADEIRA_VCREDIST = 1
env.MADEIRA_VCREDIST_X86 Text

0: 32-bit programs keep Wine's own C++ runtime instead of the Microsoft x86 runtime the app downloaded (Documents/vcruntime32)

Type: Text

env.MADEIRA_VCREDIST_X86 = value
env.MADEIRA_WAIT_CHILDREN Text

A launcher stub that starts the game and exits at once (GTA V Enhanced: PlayGTAV.exe -> GTA5_Enhanced.exe) must not end the session -- stopping the wineserver here killed the game while it loaded. If a child process that is not a crash r...

Type: Text

env.MADEIRA_WAIT_CHILDREN = value
env.MADEIRA_WINE_VCRT Text

Layer Microsoft's real VC++ Runtime DLLs ON TOP of the ARM64EC bundle (only for x86_64 guests). These overwrite Wine's stub builtins — Wine then loads the real MS x86_64 implementation (via FEX) instead of its partial ARM64EC reimplement...

Type: Text

env.MADEIRA_WINE_VCRT = value
env.MADEIRA_WORKDIR Text

set by the library for one launch: the working folder (Steam's, or the entry's); not a setting

Type: Text

env.MADEIRA_WORKDIR = value
env.MADEIRA_WOW_HOLD_FOR_GAME On/off

0: any 32-bit program may take the held window, as before 2026-11-02

Type: On/off · Default: 1

env.MADEIRA_WOW_HOLD_FOR_GAME = 1
fexfail Text

deterministic call-ret allocation failure injection. Documents/madeira-fexfail.txt holds "reserve:N" or "commit:N". The containment path it exercises only occurs naturally when a title exhausts the emulator's address band, and onl...

Type: Text

fexfail = value
gl-backend Text

OpenGL backend for the winios GL driver (build/win32u-unix/opengl_ios.c): zink - desktop OpenGL 3.3-4.x: Mesa OSMesa + Zink on MoltenVK, from the bundle's gl/ folder (build/mesa-ios, build/moltenvk-ios) gles - Apple's OpenGL ES 3.0 (EAGL...

Type: Text

gl-backend = value
mono-bridge Text

wine-mono backpatcher bridge A/B. Documents/madeira-mono-bridge.txt == "1" sets MADEIRA_WINEMONO_BRIDGE, which arms FEX's Mono code-patching optimisation for wine-mono (recognised since but activation left opt-in because the...

Type: Text

mono-bridge = value
mono-suspend Text

Mono suspend-policy A/B. Documents/madeira-mono-suspend.txt containing "preemptive" (or "coop"/"hybrid") sets MONO_THREADS_SUSPEND for wine-mono, so the comparison needs no rebuild. EXPERIMENT, NOT A FIX, and deliberately not a de...

Type: Text

mono-suspend = value
pencil-mouse On/off

Apple Pencil as a mouse

1: the Apple Pencil acts as a mouse. Touching the screen is a left press and drag as before; hovering above it moves the pointer; squeezing an Apple Pencil Pro right-clicks where it is. Ignored in mouse-look (relative) mode. A game's own config can set it. [pencil] line in the log.

Type: On/off · Default: 0

pencil-mouse = 1
real-suspend Text

this session, or nil to leave it unset. Without it a Wine SuspendThread only snapshots the target's registers while the thread keeps running (build/wineserver/mach_ios.c). A Unity IL2CPP game's garbage collector suspends every thr...

Type: Text

real-suspend = value
remote Text

remote Metal backend. Documents/madeira-remote.txt holds "<host-ip> <token>" and routes winemetal to a Metal daemon on that host instead of the local device. The mode is decided ONCE per process: flipping it later would leave hand...

Type: Text

remote = value
remote-batch Text

coalesced remote messages. Documents/madeira-remote-batch.txt == "1" makes the pre-submission flush send many buffer ranges per round trip and drains autorelease pools in one call. It is OPT-IN because the measurement it is meant ...

Type: Text

remote-batch = value
shadow Text

shadow-pack mode. Documents/madeira-shadow.txt == "1" packs and validates every real render batch into the remote wire format, then discards it and renders locally as normal. Exercises the packer against live traffic where being w...

Type: Text

shadow = value
swap-canary On/off

madeira.cfg swap-canary = 1

Type: On/off · Default: 0

swap-canary = 1
swap-min-kb Number

madeira-bcd: swap-min-kb (madeira.cfg or the game's config) lowers the tier's 8 MB eligibility floor. Upstream's virtual_ios.c reads MADEIRA_SWAP_MIN_KB only in its "blocks" coverage, so swap-min-kb selects that; an env.MADEIRA_SWAP_COVE...

Type: Number · Default: 0

swap-min-kb = 0
tf-trace Text

Theorafile call tracer. Documents/madeira-tf-trace.txt == "1" redirects libtheorafile's tf_* exports through wrappers in tftrace-x64.dll that call the original and report the RETURN value. The intro decodes and plays, the stream r...

Type: Text

tf-trace = value
usd-time Text

Windows shared-data clock A/B. Documents/madeira-usd-time.txt == "1" makes wineserver update KUSER_SHARED_DATA's SystemTime, InterruptTime and TickCount again. Without it those stay frozen at their init values, so GetTickCount/Env...

Type: Text

usd-time = value
valley-args Text

AncientGame-Win64-Shipping.exe ValleyoftheAncient and nothing else, which is why the launcher is skipped here. Flags come from Documents/madeira-valley-args.txt so a UE switch can be tried without rebuilding and reinstalling. The default...

Type: Text

valley-args = value
wx Text

W^X A/B switch. Documents/madeira-wx.txt containing "0" disables page demotion for the SAME binary, so the on/off comparison needs one rebuild, not two. The previous gate read container paths that can never exist, so it silently f...

Type: Text

wx = value
wxprobe Text

W^X A/B probe. Documents/madeira-wxprobe.txt == "1" runs it. Loading xtajit64.dll faults writing its .rdata on the jailbroken research VM and not on this phone, with CS_DEBUGGED live in both, so attachment is not the variable. Eit...

Type: Text

wxprobe = value

Direct3D 9/10/11 (DXMT)

env.DXMT_AIRCONV_DUMP Text

Env-gated metallib dump: point DXMT_AIRCONV_DUMP at a directory and every DXSOCompile call drops a {kind}_{hash}.metallib there. Disassemble with xcrun air-objdump -d <file> to inspect what AGX actually receives. Only meant for triage ...

Type: Text

env.DXMT_AIRCONV_DUMP = value
env.DXMT_API_CENSUS Text

No description written yet.

Type: Text

env.DXMT_API_CENSUS = value
env.DXMT_CACHE_STATS Text

Opt-in diagnostics: DXMT_CACHE_STATS=1 logs hit/miss counts.

Type: Text

env.DXMT_CACHE_STATS = value
env.DXMT_CAPTURE_EXECUTABLE Text

No description written yet.

Type: Text

env.DXMT_CAPTURE_EXECUTABLE = value
env.DXMT_CAPTURE_FRAME Text

No description written yet.

Type: Text

env.DXMT_CAPTURE_FRAME = value
env.DXMT_CENSUS_THROTTLE On/off

first report of the process is always emitted too, so a run that dies inside the first 10 s still leaves one. * Wall time, not the seq id: the seq id advances at the GPU's pace, so a per-N-seq gate throttles by frame rate and not by time...

Type: On/off · Default: 32-bit only

env.DXMT_CENSUS_THROTTLE = 1
env.DXMT_CLEAR_DISCARD_STORE On/off

MADEIRA : DXMT_CLEAR_DISCARD_STORE is a Madeira switch (util_madeira_switch.hpp), on by default only in the i386 build.

Type: On/off · Default: 32-bit only

env.DXMT_CLEAR_DISCARD_STORE = 1
env.DXMT_CMDLIST_KEEP_BLOCK Text

No description written yet.

Type: Text

env.DXMT_CMDLIST_KEEP_BLOCK = value
env.DXMT_CMD_CENSUS Text

No description written yet.

Type: Text

env.DXMT_CMD_CENSUS = value
env.DXMT_CONFIG Text

Load either $DXMT_CONFIG_FILE or $PWD/dxmt.conf

Type: Text

env.DXMT_CONFIG = value
env.DXMT_CONFIG_FILE Text

Load either $DXMT_CONFIG_FILE or $PWD/dxmt.conf

Type: Text

env.DXMT_CONFIG_FILE = value
env.DXMT_D9_ANISO_LIMIT Text

Written only by the encode thread (Resolve allocates, commit seals); opt into the DXMT_DEBUG single-writer assertion. single_writer= true

Type: Text

env.DXMT_D9_ANISO_LIMIT = value
env.DXMT_D9_BATCH_READBACK Text

No description written yet.

Type: Text

env.DXMT_D9_BATCH_READBACK = value
env.DXMT_D9_BINDING_PRUNE Text

The compiler emits bindings only for sampled stages. Avoid sampler-cache probes, Metal texture-view creation and resource retention for stale bindings outside that mask. Fixed-function combiners retain their path.

Type: Text

env.DXMT_D9_BINDING_PRUNE = value
env.DXMT_D9_CANONICAL_BLEND Text

Disabled blending ignores all six operation/factor fields. Canonicalize before both hashing and collision checks to share the same Metal PSO.

Type: Text

env.DXMT_D9_CANONICAL_BLEND = value
env.DXMT_D9_EXTENTLOG Text

— THE EXTENT LINE IS NOT A TRACE, IT IS THE ANSWER. "The right fifth of the picture is missing" has exactly one arithmetic cause in this path -- a back buffer presented 1:1 into a destination narrower than it is -- and exactly one...

Type: Text

env.DXMT_D9_EXTENTLOG = value
env.DXMT_D9_LATE_READBACK Text

Opt-in (default off). Serves tiny GetRenderTargetData readbacks, such as a 1x1 exposure sample, one frame late instead of waiting on the GPU. Applies to 32-bit D3D9 games that read a small render target back every frame.

Type: Text

env.DXMT_D9_LATE_READBACK = value
env.DXMT_D9_LOCKLOG Text

managed sweep, a plain lock pushes its own rect, and a SYSTEMMEM lock pushes nothing because UpdateTexture is the consumer. Those are four different bugs wearing one symptom. Deduped on (pool, usage, format, extent, full-vs-sub, flags) a...

Type: Text

env.DXMT_D9_LOCKLOG = value
env.DXMT_D9_NODIRTY_SWEEP Text

mirror, the GPU copy kept whatever it last received, and only an explicit AddDirtyRect or EvictManagedResources could ever dislodge them. A texture that is written once, drawn, then rewritten in place therefore kept showing its first con...

Type: Text

env.DXMT_D9_NODIRTY_SWEEP = value
env.DXMT_D9_PIPELINE_STATS Text

reference compiles a cold pipeline synchronously at the draw site (wined3d on its CS thread, DXVK's default and non-GPL-fallback paths, and the d3d11 sibling's blocking GetPipeline). Skipping the draw instead, the way an async fork does,...

Type: Text

env.DXMT_D9_PIPELINE_STATS = value
env.DXMT_D9_QUERY_ADAPTIVE Text

the old lifetime count penalized an asynchronous culling loop after its third check, even if those checks were a frame apart. Keep cooperative back-pressure for tight polling only. A 250us gap starts a new burst; completed querie...

Type: Text

env.DXMT_D9_QUERY_ADAPTIVE = value
env.DXMT_D9_READBACK_STATS Text

No description written yet.

Type: Text

env.DXMT_D9_READBACK_STATS = value
env.DXMT_D9_RENAME_WAIT Text

Rename drain from thebcd69/bcd-dxmt, commit 8ae252b (LGPL-2.1-or-later).

Type: Text

env.DXMT_D9_RENAME_WAIT = value
env.DXMT_D9_SCENE_BATCH Text

Written only by the encode thread (Resolve allocates, commit seals); opt into the DXMT_DEBUG single-writer assertion. single_writer= true

Type: Text

env.DXMT_D9_SCENE_BATCH = value
env.DXMT_D9_SHADER_PRUNE Text

The compiler's binding pre-scan and this metadata mask use the same dxso_opcode_samples/dxso_sampling_slot helpers (including SM1 implicit stages). Unread slots never enter its signature or lowering. Keeping their live texture kinds in t...

Type: Text

env.DXMT_D9_SHADER_PRUNE = value
env.DXMT_D9_SMALL_MIRROR_CACHE Text

Small MANAGED mirrors are inexpensive, but reconstructing even a tiny one drains the GPU queue. Keep a bounded working set without changing LockRect visibility or discarding the CPU's authoritative bytes. Shared across devices in this mo...

Type: Text

env.DXMT_D9_SMALL_MIRROR_CACHE = value
env.DXMT_D9_SUBMIT_STATS Text

Device lock serializes callers. Report causes, not just GPU totals: an upload queue can also submit buffers independently of these chunks.

Type: Text

env.DXMT_D9_SUBMIT_STATS = value
env.DXMT_D9_UPLOAD_COMMIT_MB Text

No description written yet.

Type: Text

env.DXMT_D9_UPLOAD_COMMIT_MB = value
env.DXMT_D9_VIRTUAL_MODE Text

Fullscreen rect: the window's monitor origin plus the backbuffer extent. on iOS the old borderless-only path left a large fullscreen window on a smaller virtual desktop, so pointer clamping stopped short. This is a virtual win32u...

Type: Text

env.DXMT_D9_VIRTUAL_MODE = value
env.DXMT_DISPLAY_MODE_STATS Text

MADEIRA : opt-in diagnostics, DXMT_DISPLAY_MODE_STATS=1.

Type: Text

env.DXMT_DISPLAY_MODE_STATS = value
env.DXMT_DUMP_D9_LAYOUT Text

Triage: dump unique layouts under DXMT_DUMP_D9_LAYOUT=1 so we can see what D3DDECLTYPE -> MTLAttributeFormat the host is feeding the manual-fetch path. Useful when a class of draws renders wrong and the suspect is a format mismatch insid...

Type: Text

env.DXMT_DUMP_D9_LAYOUT = value
env.DXMT_DUMP_D9_SHADER Text

One-shot env-var read. DXMT_DUMP_D9_SHADER=1 enables a per-create summary line via Logger::warn (so it shows up in d3d9.log alongside the first-call traces). Off by default to avoid unconditional spam from apps that create hundreds of sh...

Type: Text

env.DXMT_DUMP_D9_SHADER = value
env.DXMT_DUMP_PATH Text

Optional bytecode-to-disk dump. Empty -> disabled. Set to a writable directory path; we write one file per unique bytecode hash, so the session ends with a directory containing every shader the app created.

Type: Text

env.DXMT_DUMP_PATH = value
env.DXMT_DYN_KEEP Text

retires ~600 names a frame; as soon as the GPU catches up, the trim below frees all but 64, and the next frame mints ~540 brand-new Metal buffers for it again: 15-30k fresh MTLBuffers a second (~1000 a frame, avg 438 bytes), each a newBu...

Type: Text

env.DXMT_DYN_KEEP = value
env.DXMT_DYN_KEEP_KB Text

No description written yet.

Type: Text

env.DXMT_DYN_KEEP_KB = value
env.DXMT_ENABLE_NVEXT Text

Report an NVIDIA GPU (all games)

1: DXGI names NVIDIA as the vendor, DXMT's NVAPI answers and win32u registers the display adapter as a GeForce RTX 3060 (driver 581.57). Per game: Game details > Report an NVIDIA GPU, which also sets the matching DXGI device id.

Type: Text

env.DXMT_ENABLE_NVEXT = value
env.DXMT_IOS_CACHE_DIR Text

shader cache persists. With the switch on, a relative path resolves under the app's NSCachesDirectory instead and a directory that cannot be created fails cleanly. * Decided per caller, like winemetal_unix.c's madeira_switch_for_caller: ...

Type: Text

env.DXMT_IOS_CACHE_DIR = value
env.DXMT_LOG_LEVEL Text

No description written yet.

Type: Text

env.DXMT_LOG_LEVEL = value
env.DXMT_LOG_PATH Text

guard on the bool, NOT on the stream -- see log.hpp.

Type: Text

env.DXMT_LOG_PATH = value
env.DXMT_MAX_VRAM_MB Text

Returning the strictly-truthful UMA answer (0) drives era-typical engines into recreate-every-frame fallbacks. Mirror dxgi/d3d11: half of recommendedMaxWorkingSetSize (available_texture_mem_bytes halves on unified memory), clamped below ...

Type: Text

env.DXMT_MAX_VRAM_MB = value
env.DXMT_METALFX_SPATIAL_SWAPCHAIN Text

No description written yet.

Type: Text

env.DXMT_METALFX_SPATIAL_SWAPCHAIN = value
env.DXMT_PRECISE_MINMAX Text

madeira DXBC min/max are IEEE minNum/maxNum: when one operand is NaN the other one is returned, and shaders rely on max(0, x) to throw NaNs away. Metal's fast_fmin/fast_fmax leave the NaN case undefined, so a NaN from a degenerat...

Type: Text

env.DXMT_PRECISE_MINMAX = value
env.DXMT_QUERY_SETTLE_EMPTY On/off

No description written yet.

Type: On/off · Default: 32-bit only

env.DXMT_QUERY_SETTLE_EMPTY = 1
env.DXMT_REMOTE_BATCH Text

coalescing is OPT-IN. With it off this build behaves exactly as did, which is what makes a matched baseline measurement possible.

Type: Text

env.DXMT_REMOTE_BATCH = value
env.DXMT_REMOTE_METAL Text

Decided once. DXMT_REMOTE_METAL=<host-ip> turns it on. Decided exactly once. The gate sits on EVERY dispatch entry, so without this two threads racing the first call would each open a socket: one leaks and wmtr_fd changes under a call al...

Type: Text

env.DXMT_REMOTE_METAL = value
env.DXMT_RING_OVERSIZE_REUSE On/off

DXMT_RING_OVERSIZE_REUSE is a Madeira switch (util_madeira_switch.hpp): on by default only in the i386 build. Every 64-bit build keeps the upstream block lifetime unless it is set.

Type: On/off · Default: 32-bit only

env.DXMT_RING_OVERSIZE_REUSE = 1
env.DXMT_SHADER_CACHE Text

No description written yet.

Type: Text

env.DXMT_SHADER_CACHE = value
env.DXMT_SHADER_CACHE_PATH Text

No description written yet.

Type: Text

env.DXMT_SHADER_CACHE_PATH = value
env.DXMT_SHADOW_PACK Text

No description written yet.

Type: Text

env.DXMT_SHADOW_PACK = value
env.DXMT_SMALL_RINGS Text

Small DXMT staging rings for these programs

Read by DXMT's d3d11 with the small-rings change. Program file names separated by ';' (e.g. Launcher.exe;SocialClubHelper.exe), or 1 for every program: in those programs DXMT's staging ring, copy-temp ring and upload heap use 4 MB Metal blocks instead of 32 MB. A ring keeps its blocks until 300 later submissions and an idle program keeps them for good (Rockstar Games Launcher 132 MB, Social Club 68 MB through a whole RDR2 session). Larger uploads still get a block of their own; each named program logs one [small-rings] line. Unset or 0 (default): 32 MB, as before. Set it in the game's own file; read when the program starts.

Type: Text

env.DXMT_SMALL_RINGS = value
env.DXMT_USE_DEFAULT_METAL_CACHE Text

Pin Metal's own shader and pipeline cache to the per-executable directory the disk shader cache uses (the d3d11 backend does the same at provider init). Without it the OS cache keys off the wine loader's identity and pipeline links never...

Type: Text

env.DXMT_USE_DEFAULT_METAL_CACHE = value
env.DXMT_WAIT_ON_ADDRESS On/off

A Madeira switch (util_madeira_switch.hpp): the i386 build uses the address wait by default; every 64-bit build keeps std::atomic, which is upstream behaviour, unless DXMT_WAIT_ON_ADDRESS is set. Only the non-upstream choice is logged.

Type: On/off · Default: 32-bit only

env.DXMT_WAIT_ON_ADDRESS = 1
env.DXMT_WSI_MODE_TABLE On/off

No description written yet.

Type: On/off · Default: 32-bit only

env.DXMT_WSI_MODE_TABLE = 1
env.DXMT_WSI_MONITOR_IDENTITY On/off

The native frontend (DXMT_MADEIRA) has no user32 boundary and always uses the internal singleton.

Type: On/off · Default: 32-bit only

env.DXMT_WSI_MONITOR_IDENTITY = 1
env.DXMT_ZERO_BUFFER_POW2 On/off

MADEIRA : with DXMT_ZERO_BUFFER_POW2, grow to the next power of two (at least 1 MB) instead of the exact request. Each growth costs a flushInternal(), and a loading screen asking for slowly rising sizes regrew the buffer 322 time...

Type: On/off · Default: 32-bit only

env.DXMT_ZERO_BUFFER_POW2 = 1
env.MADEIRA_D3D11_NO_VIDEO_DEVICE On/off

Direct3D 11: use software video presentation

1: reject D3D11 devices explicitly requested with VIDEO_SUPPORT so Unity can fall back to CPU-backed Media Foundation samples. Direct3D rendering still uses Metal. Set per game.

Type: On/off · Default: 0

env.MADEIRA_D3D11_NO_VIDEO_DEVICE = 1
env.MADEIRA_D3D9 Text

the d3d9 key's value: emulated (default) or native = DXMT's i386 shim; wined3d = Wine's d3d9 on wined3d/OpenGL for 32- and 64-bit programs

Type: Text

env.MADEIRA_D3D9 = value
env.MADEIRA_D3D9_BATCH_BUDGET Text

No description written yet.

Type: Text

env.MADEIRA_D3D9_BATCH_BUDGET = value
env.MADEIRA_D3D9_BATCH_USED Text

charge used bytes and trim sparse small captures, so retention and the pressure submit follow real work. MADEIRA_D3D9_BATCH_USED=0 restores 's capacity charge and 8 MiB threshold.

Type: Text

env.MADEIRA_D3D9_BATCH_USED = value
env.MADEIRA_D3D9_CENSUS Text

No description written yet.

Type: Text

env.MADEIRA_D3D9_CENSUS = value
env.MADEIRA_D3D9_CENSUS_EVERY Text

the ring is opt-in now. See the note in d3d9_census.hpp -- it is forensics, not a measurement, and it was the second emulated locked RMW on a 5540-calls-per-frame path. MADEIRA_D3D9_LAST=1 in Documents/madeira-env.txt brings it ba...

Type: Text

env.MADEIRA_D3D9_CENSUS_EVERY = value
env.MADEIRA_D3D9_DIRECT_MAP Text

Direct mapping (d3d9_buffer_map.hpp): a 64-bit guest can address Metal's own allocation, so both premises of the mirror are gone for it. The native ARM64 frontend also builds without __i386__ but serves 32-bit guests (DXMT_MADEIRA), so i...

Type: Text

env.MADEIRA_D3D9_DIRECT_MAP = value
env.MADEIRA_D3D9_INDEX_RANGE On/off

Direct3D 9: upload only the index bytes a draw reads

On by default. A 32-bit Direct3D 9 game writes its index buffers through a copy Madeira keeps; an indexed draw now copies only the indices it reads into the buffer the GPU reads, instead of the whole buffer before every draw after a lock (the slowdown in engines that lock a little of one big index buffer before each draw, such as Call of Duty's). A lock without NOOVERWRITE still gives the next draw a fresh buffer, so draws already recorded keep what they read. [d3d9-index-range] lines in the log say how much was copied. 0: the whole-buffer copy, as before. Read once per session.

Type: On/off · Default: 1

env.MADEIRA_D3D9_INDEX_RANGE = 1
env.MADEIRA_D3D9_LAST Text

the ring is opt-in now. See the note in d3d9_census.hpp -- it is forensics, not a measurement, and it was the second emulated locked RMW on a 5540-calls-per-frame path. MADEIRA_D3D9_LAST=1 in Documents/madeira-env.txt brings it ba...

Type: Text

env.MADEIRA_D3D9_LAST = value
env.MADEIRA_D3D9_LOCKCHECK Text

No description written yet.

Type: Text

env.MADEIRA_D3D9_LOCKCHECK = value
env.MADEIRA_D3D9_LUMINANCE_RT On/off

Direct3D 9: luminance formats as render targets

On by default. A Direct3D 9 program may render into an L8, A8L8 or L16 texture (one-channel targets for ambient occlusion, blur passes or masks), as native drivers and DXVK allow; DXMT used to refuse the texture, and a program that builds such targets through its engine's format table then got none and could sit on its loading screen for good. The storage is R8Unorm, RG8Unorm or R16Unorm, renderable on every Metal GPU; the shader's .r lands in the luminance channel and samples read back as (L, L, L, 1). 0: refuse them, as before. Read once per session.

Type: On/off · Default: 1

env.MADEIRA_D3D9_LUMINANCE_RT = 1
env.MADEIRA_D3D9_MIRROR_BATCH Text

ensureMirror (run by the surface before this) re-allocated a blank backing; download the face's bytes back from the Metal texture so the Lock hands out the real contents. every stale face/level in one drain (see MTLD3D9Texture::m...

Type: Text

env.MADEIRA_D3D9_MIRROR_BATCH = value
env.MADEIRA_D3D9_NATIVE_CENSUS Text

Read the two knobs once, from _d3d9_init, on the guest's own thread.

Type: Text

env.MADEIRA_D3D9_NATIVE_CENSUS = value
env.MADEIRA_D3D9_NATIVE_CENSUS_EVERY Text

Read the two knobs once, from _d3d9_init, on the guest's own thread.

Type: Text

env.MADEIRA_D3D9_NATIVE_CENSUS_EVERY = value
env.MADEIRA_D3D9_TRACE Text

No description written yet.

Type: Text

env.MADEIRA_D3D9_TRACE = value
env.MADEIRA_D3D9_X64 Text

MADEIRA: the 64-bit (ARM64EC) build is the x64 programs' d3d9.dll, in place of Wine's, which needs OpenGL and so always failed to create here. MADEIRA_D3D9_X64=0 makes creation fail the same way again.

Type: Text

env.MADEIRA_D3D9_X64 = value
env.MADEIRA_D9_LOCK_BACKOFF Text

~2000 pauses + a yield per round: 256 rounds is several milliseconds of pure yielding before the waiter starts parking for 1 ms at a time.

Type: Text

env.MADEIRA_D9_LOCK_BACKOFF = value
env.MADEIRA_D9_LOCK_DIAG Text

No description written yet.

Type: Text

env.MADEIRA_D9_LOCK_DIAG = value
env.MADEIRA_DXGI_BUDGET_EVENTS On/off

Tell the game when its video memory budget changes

Read by DXMT's dxgi with the budget-event change. The video memory budget DXGI reports shrinks as Madeira nears its memory limit (vram-trim-mb below it). 1: a game's budget-change event is registered for real, signalled at once and again whenever the budget moves by 32 MB, so a game that waits for it (Red Dead Redemption 2) reads the smaller budget and frees textures. Off (default): the registration is refused, as before. Set it in the game's own file; read at session start.

Type: On/off · Default: 0

env.MADEIRA_DXGI_BUDGET_EVENTS = 1
env.MADEIRA_DXMT_SCHED_FIFO Text

no thread handles exist here; refuse rather than lie

Type: Text

env.MADEIRA_DXMT_SCHED_FIFO = value
env.MADEIRA_FRAMEGEN Text

3. runs MetalFX's frame interpolator (MTLFXFrameInterpolator, iOS 26) on the two frames, that motion field and a flat depth, 4. presents the generated frame at once and the real one half a frame later (presentDrawable:atTime:). The panel...

Type: Text

env.MADEIRA_FRAMEGEN = value
env.MADEIRA_FRAMEGEN_ONE_LAYER Text

No description written yet.

Type: Text

env.MADEIRA_FRAMEGEN_ONE_LAYER = value
env.MADEIRA_IDX_REALIGN Text

madeira-bcd: realigned 16-bit indices -- reserve argument-buffer room for a 16-bit draw whose index offset is not 4-byte aligned; 0 = not needed.

Type: Text

env.MADEIRA_IDX_REALIGN = value
env.MADEIRA_MIP_CLAMP_AUTO Text

No description written yet.

Type: Text

env.MADEIRA_MIP_CLAMP_AUTO = value
env.MADEIRA_PRESENT_LIMITER Text

sleeps to an absolute deadline on the same timebase the scheduler uses, so it does not accumulate the per-iteration error a relative nanosleep ladder does and it does not quantise to a timer tick -- the failure mode the brief calls out, ...

Type: Text

env.MADEIRA_PRESENT_LIMITER = value
env.MADEIRA_PRESENT_PIXELS On/off

WSI window extents are Windows pixels, not UIKit points. Applying the phone's 3x scale again made a 720p present render into a 4K drawable. Core Animation already maps that drawable onto the host view in points. Keep the correcti...

Type: On/off · Default: 32-bit only

env.MADEIRA_PRESENT_PIXELS = 1
env.MADEIRA_VFETCH_ALIGN1 Text

No description written yet.

Type: Text

env.MADEIRA_VFETCH_ALIGN1 = value
env.MADEIRA_VFETCH_BOUNDS Text

madeira-bcd: vertex fetch bounds (tools/patch-dxmt-vfetch-bounds.py) -- D3D10 reads zero past the end of the binding; route such a fetch to the null-binding branch of pull_vec4_from_addr instead of reading on. Default: SM 4.x shaders onl...

Type: Text

env.MADEIRA_VFETCH_BOUNDS = value
env.MADEIRA_WRITE_COMBINED Text

no write-combined CPU mappings. DXMT asks for MTLCPUCacheModeWriteCombined on what the CPU only writes (dynamic buffers and textures, upload staging). Under FEX's TSO emulation every x86 integer store is an STLR, and a store-rele...

Type: Text

env.MADEIRA_WRITE_COMBINED = value
pso-warm Number

pipeline cache warm-up: N background compiles of every lazy pipeline at creation (1-4; 0 = off)

Type: Number · Default: 0

pso-warm = 0
ram-reserve-mb Number

RAM left to iOS, MB; 0 = limit only

Type: Number · Default: 1536

ram-reserve-mb = 1536
sampler-reduction Number

madeira-bcd: native sampler reduction (tools/patch-winemetal-sampler-reduction.py)

Type: Number · Default: 0

sampler-reduction = 0
stale-probe Number

the probe found its bug ; off unless madeira.cfg stale-probe = 1

Type: Number · Default: 0

stale-probe = 0
vram-count-donor On/off

Video memory budget counts donated RAM

The video memory budget a game reads shrinks as memory runs short (vram-trim-mb), judged by the app's own memory. 1: the donor pool's memory counts as well, since it is the device's RAM even though it is not under the app's limit, so with a full pool on a phone with less RAM the game is told to keep fewer textures. Off by default (a test option). Read at session start.

Type: On/off · Default: 0

vram-count-donor = 1
vram-mb Number

Video memory budget (MB)

madeira.cfg vram-mb = N

Type: Number · Default: 0

vram-mb = 0
vram-trim-mb Number

madeira.cfg vram-trim-mb = distance below the kill line where the trim starts (default 1536, the value); 0 = never trim. ph-rdr56: raising vram-mb to 3072 doubled the snow-scene frame rate, but in the city the footprint re...

Type: Number · Default: 1536

vram-trim-mb = 1536

Wine core (ntdll)

cpu-count Number

Reported CPU count (0 = device)

(experiment: RDR2 sizes its job system from it; iPhone = 2 P + 4 E cores).

Type: Number · Default: 0

cpu-count = 0
env.DOTNET_EnableWriteXorExecute Text

.NET runtime: W^X mapping

Passed into the game's environment and read by the .NET (CoreCLR) runtime itself. 0 turns off its write-xor-execute double mapping of JIT code, for a .NET game whose JIT stops at start.

Type: Text

env.DOTNET_EnableWriteXorExecute = value
env.DOTNET_GCRegionRange Text

.NET runtime: GC region reservation

Passed into the game's environment and read by the .NET runtime: the size (hex bytes) of the address range its regions GC reserves at start, for a .NET game whose default reservation fails.

Type: Text

env.DOTNET_GCRegionRange = value
env.LC_ALL Text

Wine's locale for this game

Empty: Wine takes the user locale from the device's language. en_US.UTF-8 gives the game an English system and user locale, for a game that fails right after loading a non-English OEM code page. Read at session start.

Type: Text

env.LC_ALL = value
env.MADEIRA_AFD_EVENT_HANDLE Text

No description written yet.

Type: Text

env.MADEIRA_AFD_EVENT_HANDLE = value
env.MADEIRA_APP_DLL_SHADOW Text

Ignore these DLLs in the game's folder

Default empty. DLL names separated by ';' (e.g. vcruntime140.dll): a plain x64 copy of one of them outside C:\windows (the game's own folder) is reported as not loadable, so the loader binds the system's, as it already does for ucrtbase.dll. For a game that ships Microsoft's x64 vcruntime140.dll but not msvcp140.dll: Wine's msvcp140 cannot call that x64 copy (Crysis 3 Remastered: "MSVCP140.dll failed to initialize", c000001d). Logged as [app-dll-shadow]. Read at every DLL load.

Type: Text

env.MADEIRA_APP_DLL_SHADOW = value
env.MADEIRA_BG_QOS_DELAY_S Text

seconds the game must present before the listed processes are demoted (default 60)

Type: Text

env.MADEIRA_BG_QOS_DELAY_S = value
env.MADEIRA_BG_QOS_PROCS Text

';'-separated exe names demoted to utility QoS while the game presents; empty = off

Type: Text

env.MADEIRA_BG_QOS_PROCS = value
env.MADEIRA_CA_BUNDLE Text

iOS-Madeira: no system root store API on iOS. WineProcessBridge.m points MADEIRA_CA_BUNDLE at the bundled Mozilla cacert.pem (concatenated PEM — same format as ca-certificates.crt, which import_certs_from_file already parses).

Type: Text

env.MADEIRA_CA_BUNDLE = value
env.MADEIRA_CFG_EARLY_DOCS Text

Directory that holds the configuration: $MADEIRA_DOCS_DIR, else the app container's Documents from $CFFIXED_USER_HOME, else $HOME/Documents. * The in-app wineserver thread sets HOME to the Wine prefix (Documents/wine) before it creates i...

Type: Text

env.MADEIRA_CFG_EARLY_DOCS = value
env.MADEIRA_CFG_GAME Text

set by the app for a library game's own lines; not a madeira.cfg option

Type: Text

env.MADEIRA_CFG_GAME = value
env.MADEIRA_CHILD_ARGS Text

madeira-bcd: env.MADEIRA_CHILD_ARGS -- see child_extra_args.

Type: Text

env.MADEIRA_CHILD_ARGS = value
env.MADEIRA_CHILD_BOOT_SERIAL Text

0: child processes boot at once, side by side, as before

Type: Text

env.MADEIRA_CHILD_BOOT_SERIAL = value
env.MADEIRA_CHILD_NTDLL_STRICT Text

do not start a process on the SHARED ntdll copy. Its .data (PEB-derived loader state, module list, loader lock) belongs to another process: device log 95's conhost (started by a 32-bit browser's AllocConsole while the JIT pool wa...

Type: Text

env.MADEIRA_CHILD_NTDLL_STRICT = value
env.MADEIRA_CONHOST_HEADLESS Text

madeira-conhost-headless: a pipe cannot be a --unix console's tty (the server calls tcgetattr on it); --headless takes the same standard handles and needs no terminal device. env.MADEIRA_CONHOST_HEADLESS = 1.

Type: Text

env.MADEIRA_CONHOST_HEADLESS = value
env.MADEIRA_CONSOLE_WINDOW Text

1: consoles keep their conhost window (default: none, as with CREATE_NO_WINDOW)

Type: Text

env.MADEIRA_CONSOLE_WINDOW = value
env.MADEIRA_CPU_COUNT Text

MADEIRA_CPU_COUNT, a per-launch setting the app exports for one program, wins over the global key; unset = the key's behaviour.

Type: Text

env.MADEIRA_CPU_COUNT = value
env.MADEIRA_CS_X64 On/off

x64 fast path for EnterCriticalSection/LeaveCriticalSection/TryEnterCriticalSection. Default off (experimental). 1: an uncontended or recursive critical section is taken and released inside the x64 JIT code instead of a round trip into n...

Type: On/off · Default: 0

env.MADEIRA_CS_X64 = 1
env.MADEIRA_DEFER_SECTION_ABORT Text

MADEIRA_DEFER_SECTION_ABORT=0: a killed thread exits at once, even inside a section

Type: Text

env.MADEIRA_DEFER_SECTION_ABORT = value
env.MADEIRA_DIRCACHE On/off

Remember directory listings for file lookups

Kill switch, default 1: a file name that does not match in its exact case is looked up in an in-memory copy of its directory instead of a volume query and a directory read each time (twice when the name is absent). Source-engine games such as Team Fortress 2 probe thousands of absent paths while loading and during play. 0: as before. Read once per app run.

Type: On/off · Default: 1

env.MADEIRA_DIRCACHE = 1
env.MADEIRA_DIRCACHE_TTL_MS Number

Directory listing trust window (ms)

How long a remembered listing is used without checking the directory, while no file was created, renamed, linked or deleted through Wine. After that one stat of the directory decides whether it is read again. 0 checks it on every lookup. Read once per app run.

Type: Number · Default: 1000

env.MADEIRA_DIRCACHE_TTL_MS = 1000
env.MADEIRA_DIR_BY_PATH Text

entries skipped because their stat failed

Type: Text

env.MADEIRA_DIR_BY_PATH = value
env.MADEIRA_DIR_INFO_CACHE_MS Text

No description written yet.

Type: Text

env.MADEIRA_DIR_INFO_CACHE_MS = value
env.MADEIRA_DOCK_SESSION Text

"EnterEC wrote it" does NOT name the origin — Core.cpp says so explicitly: EnterEC storing an x64 target in State.rip is its job. The upstream producer still needs finding via x9 at DispatchJump/RetToEntryThunk/ExitToX64. A game in a Mad...

Type: Text

env.MADEIRA_DOCK_SESSION = value
env.MADEIRA_DOCS_DIR Text

Which rule chose the directory, for logging: "env", "container", "home" or "none".

Type: Text

env.MADEIRA_DOCS_DIR = value
env.MADEIRA_ECO_NATIVE On/off

Runtime helper threads on efficiency cores

1: the JIT-pool warmer (page warming and the periodic memory walks) and the stale-pointer healer run at utility QoS, on the efficiency cores, ECO on or off; neither does work a frame waits for. The wineserver thread, the exception thread, audio and the interface keep their QoS. Off (default): they keep the QoS they were created with. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_ECO_NATIVE = 1
env.MADEIRA_EC_CONHOST Text

conhost.exe is refused in an ARM64EC session, where it would crash the app (see ec_conhost_refuse); MADEIRA_EC_CONHOST=1 starts it anyway.

Type: Text

env.MADEIRA_EC_CONHOST = value
env.MADEIRA_EC_NATIVE_CHILD On/off

Start aarch64 programs in a 64-bit x86 session

off (default): an aarch64 program (services.exe, cmd.exe, conhost.exe) started in a session whose first program is 64-bit x86 (ARM64EC) is refused and CreateProcess fails at once. The session's ntdll loads the emulator into it and its threads have no CPU area, so it crashed at its first executable allocation and its exception path faulted until the storm handler ended it (testers' log, 2026-10-28: services.exe started on demand for a launcher installer, twice, 20 s each). A game that needs one starts in the Wine desktop. 1: starts them anyway; MADEIRA_EC_CONHOST=1 still lets conhost.exe through.

Type: On/off · Default: 0

env.MADEIRA_EC_NATIVE_CHILD = 1
env.MADEIRA_EXE_WINDOW_END_PARENT_MS Text

how long a program that started a copy of itself may keep running while the copy waits for its fixed base, in milliseconds, before it is ended so the copy can start; 0 never ends it

Type: Text

env.MADEIRA_EXE_WINDOW_END_PARENT_MS = value
env.MADEIRA_FILE_INFO_FULL On/off

File size queries read attributes too

Kill switch, default 0: a file's size, index or end-of-file query (GetFileSizeEx and the like) is answered from one fstat; the two extended-attribute reads that came after it fed only file attributes, which these queries do not return. 1: as before. Read once per app run.

Type: On/off · Default: 0

env.MADEIRA_FILE_INFO_FULL = 1
env.MADEIRA_FILE_TRACE Text

No description written yet.

Type: Text

env.MADEIRA_FILE_TRACE = value
env.MADEIRA_FILE_TRACE_LIMIT Text

No description written yet.

Type: Text

env.MADEIRA_FILE_TRACE_LIMIT = value
env.MADEIRA_FORCE_CONSOLE Text

iOS denies pty allocation, so isatty() above can never be true and every console-only session lands on CONSOLE_HANDLE_SHELL_NO_WINDOW -- the one value init_console excludes from every console-creating branch (kernelbase/console.c:2400). ...

Type: Text

env.MADEIRA_FORCE_CONSOLE = value
env.MADEIRA_FRAME_STATS Text

[frame] once a second: unset/0 off (default), anything else on

Type: Text

env.MADEIRA_FRAME_STATS = value
env.MADEIRA_GUEST_LOG Text

No description written yet.

Type: Text

env.MADEIRA_GUEST_LOG = value
env.MADEIRA_GUEST_LOG_ERRORS Text

No description written yet.

Type: Text

env.MADEIRA_GUEST_LOG_ERRORS = value
env.MADEIRA_GUEST_LOG_LIMIT Text

No description written yet.

Type: Text

env.MADEIRA_GUEST_LOG_LIMIT = value
env.MADEIRA_HW_REGISTRY Text

Default 1: wineboot's volatile HKLM\HARDWARE\DESCRIPTION\System keys. 0: none (no session had them before). 2: also the Session Manager\Environment values.

Type: Text

env.MADEIRA_HW_REGISTRY = value
env.MADEIRA_INITIAL_CWD Text

iOS-Madeira override: MADEIRA_INITIAL_CWD env var lets the bridge specify the initial NT path directly (e.g. "C:\\Program Files\\Thumper\\") when iOS unix_to_nt_file_name can't resolve drive_c via dosdevices.

Type: Text

env.MADEIRA_INITIAL_CWD = value
env.MADEIRA_INIT_FAULT_DIAG Text

hand the fault back: the instruction re-faults under the previous handler

Type: Text

env.MADEIRA_INIT_FAULT_DIAG = value
env.MADEIRA_IOSB_DEAD_TARGET Text

IO_STATUS_BLOCK32 one guest window iOS maps nothing below 4 GB

Type: Text

env.MADEIRA_IOSB_DEAD_TARGET = value
env.MADEIRA_IO_STATUS_OWNER Text

leaves it pointing at the last WoW64 child, so neither value identifies the CALLER's I/O ABI (an I/O status block must be written in the layout of the process that owns it). The guest-window base of the calling pseudo-process does: nonze...

Type: Text

env.MADEIRA_IO_STATUS_OWNER = value
env.MADEIRA_JAPANESE On/off

Japanese locale and fonts

Default off. 1: the game runs with a Japanese system and user locale (LC_ALL = ja_JP.UTF-8, ANSI and OEM code page 932) and the extra code page tables (env.MADEIRA_NLS_EXTRA), and a Japanese font (Noto Sans JP) is installed in C:\windows\Fonts with MS Gothic, MS PGothic, MS UI Gothic, MS Mincho, Meiryo and Yu Gothic mapped onto it. For Japanese games and visual novels whose text shows as squares or gibberish, or that do not start. Game details › Compatibility › Japanese locale sets it for one game. Logged as [japanese]. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_JAPANESE = 1
env.MADEIRA_JITLESS Text

Interpreted V8 costs 5-20x on all of Steam's UI JavaScript, so this is the largest single startup lever we have. MADEIRA_JITLESS=0 turns it off; default stays ON (unchanged). (device logs 111-112, Big Picture): CEF's verbose file ...

Type: Text

env.MADEIRA_JITLESS = value
env.MADEIRA_JIT_ENV_INHERIT Text

0: a child's environment stays as its creator built it

Type: Text

env.MADEIRA_JIT_ENV_INHERIT = value
env.MADEIRA_KEYED_EVENT_PER_PROCESS On/off

A default keyed event per process

On (default): each Windows process gets its own keyed event for the waits and wakes that pass no handle (RtlRunOnce among them), created on first use. 0: every process uses the one the first process created, as before, whose handle is not valid in the others (Slay the Spire 2 failed in RtlRunOnceComplete). Read once per app run.

Type: On/off · Default: 1

env.MADEIRA_KEYED_EVENT_PER_PROCESS = 1
env.MADEIRA_LOCK_ORPHAN One of a list

Orphan-lock reaper mode

Default and stamped: only a lock seen held by FEX can be released, after three monitor cycles with the same lock word and no live owner stamp. Guest locks are never released. 0: no orphan-lock releases. The dead-thread reaper is unchanged. Restart the session after changing it.

Type: One of a list · Choices: , Only stamped locks (default), stamped, Only stamped locks, 0, Off

env.MADEIRA_LOCK_ORPHAN = 
env.MADEIRA_LOG_THROTTLE Text

No description written yet.

Type: Text

env.MADEIRA_LOG_THROTTLE = value
env.MADEIRA_NLS_EXTRA On/off

Extra code page tables

Default on. A code page table that is not in the app's nls folder (932, 936, 949, 950, 874, 1250, 1251, 1253-1258, the OEM pages 720-869 and 20866) is read from the nls/extra folder when Wine asks for it, so programs started on a non-English device language (Chinese, Japanese, Korean, Russian and others) get their code page. 0: turn it off; such a request then fails as in older builds (GetCPInfo and MultiByteToWideChar return an error). Logged as [nls-extra]; [nls-missing] names a table that was not found. Read at every request.

Type: On/off · Default: 1

env.MADEIRA_NLS_EXTRA = 1
env.MADEIRA_NO_UNIXCALL_DIRECT Text

iOS-Madeira Round 7 (2026-07-04): de-fault the unix-call path. Pool-executing EC callers read this slot and blr its value. With the baseline PE VA they exec-fault (~100 Mach round trips/present, ~0.5ms wall each = the bulk of the gamep...

Type: Text

env.MADEIRA_NO_UNIXCALL_DIRECT = value
env.MADEIRA_NSI_CACHE_MS Text

On by default (500 ms): an identical interface, address or route table read within this many milliseconds reuses the last result. 0 reads the host every time; at most 5000.

Type: Text

env.MADEIRA_NSI_CACHE_MS = value
env.MADEIRA_NSI_NETWORK_TABLES Text

On by default: programs see this device's network interfaces, IP addresses and routes. 0 serves none of them, as before.

Type: Text

env.MADEIRA_NSI_NETWORK_TABLES = value
env.MADEIRA_PIPE_TRACE Text

No description written yet.

Type: Text

env.MADEIRA_PIPE_TRACE = value
env.MADEIRA_PIPE_TRACE_BYTES Text

No description written yet.

Type: Text

env.MADEIRA_PIPE_TRACE_BYTES = value
env.MADEIRA_PIPE_TRACE_LIMIT Text

No description written yet.

Type: Text

env.MADEIRA_PIPE_TRACE_LIMIT = value
env.MADEIRA_POWER_GOV_BAND_MJ Text

energy (mJ) the running balance may drift before ECO switches (1000)

Type: Text

env.MADEIRA_POWER_GOV_BAND_MJ = value
env.MADEIRA_POWER_GOV_MW Text

process CPU power target (mW) while a game presents; unset/0 = off

Type: Text

env.MADEIRA_POWER_GOV_MW = value
env.MADEIRA_PROBES Text

Madeira: MADEIRA_PROBES picks which always-on profilers start, for timing runs: unset/1 = all (as before); "light" = only the xprobe ([xp]/[xp-t]/[xp-api], counters read 4x a second, no thread is ever suspended); 0 = none. The thread sam...

Type: Text

env.MADEIRA_PROBES = value
env.MADEIRA_PROC_GATE_STEAM Text

the full Windows Steam client (steam.exe, started by the in-session launcher or a library entry) runs its own crash reporter, hardware survey and GPU probes. These names were refused because, before a helper's crash or sel...

Type: Text

env.MADEIRA_PROC_GATE_STEAM = value
env.MADEIRA_QUIET Text

No description written yet.

Type: Text

env.MADEIRA_QUIET = value
env.MADEIRA_RESPAWN_GUARD On/off

Stop a program that keeps restarting itself

respawn-guard, default on: when a program starts a new copy of itself after 3 earlier copies of it each closed within 6 s of starting (inside 60 s), that start is refused, the log says [respawn-guard], and after the session the player is told; nothing else changes. Copies with --type= on their command line (Chromium/CEF helpers such as Battle.net's) and other programs never count (Fallout: New Vegas with FalloutNV.exe in the launcher's place started itself 32 times until a copy ran out of memory). 0: no check (old behaviour).

Type: On/off · Default: 1

env.MADEIRA_RESPAWN_GUARD = 1
env.MADEIRA_RTCS_LOG Text

all: every "[rtcs] pre" line; N: at most N a second per thread (default 10, 0 none)

Type: Text

env.MADEIRA_RTCS_LOG = value
env.MADEIRA_SC_CEF On/off

Social Club's Chromium in one process

On by default; 0 turns it off. SocialClubHelper.exe runs --single-process with PartitionAllocBackupRefPtr disabled and V8 --jitless (MADEIRA_JITLESS = 0 keeps V8's JIT), its --type= children are refused, and a process with socialclub.dll mapped that is not the helper (the game) gets no JIT-pool copy of libcef.dll: its load fails, as it did when the pool was full. No effect on programs without Social Club.

Type: On/off · Default: 1

env.MADEIRA_SC_CEF = 1
env.MADEIRA_SC_CEF_FLAGS Text

Extra SocialClubHelper.exe switches

Appended verbatim to SocialClubHelper.exe's command line while env.MADEIRA_SC_CEF is on, e.g. --disable-gpu or --enable-logging=file --v=1. A --js-flags= in it gets --jitless as its first flag (Chromium keeps only the last --js-flags=), unless MADEIRA_JITLESS = 0.

Type: Text

env.MADEIRA_SC_CEF_FLAGS = value
env.MADEIRA_SECTION_PROCESS_LIMIT Text

map_section serves both guest and native helpers. The shared WoW ceiling remains nonzero after a guest starts, but a later native helper has no guest window. Passing that ceiling to its locale/API-set mapping forces an impossible...

Type: Text

env.MADEIRA_SECTION_PROCESS_LIMIT = value
env.MADEIRA_SOCK_WIRE Text

OFF for the timing run. Each call costs a getpeername(), and this fires on every send/recv — Steam's CM ping budget is 1000 ms total. * Also note before re-enabling: the 0x17 classifier below is WRONG FOR TLS 1.3. Everything after...

Type: Text

env.MADEIRA_SOCK_WIRE = value
env.MADEIRA_SPAWN_BLOCK Text

madeira-bcd: more optional helpers, named per game. Every x64 pseudo- process copies its own system DLLs into the JIT pool and gets a 16 MB code buffer. GTA V Enhanced build 374 (2026-10-04 09:25): with SocialClubHelper.exe's 240 MB libc...

Type: Text

env.MADEIRA_SPAWN_BLOCK = value
env.MADEIRA_SPIN_DIAG Text

env.MADEIRA_SPIN_DIAG=0: no [spin] at all

Type: Text

env.MADEIRA_SPIN_DIAG = value
env.MADEIRA_SRV_FGETPATH On/off

Name opened files with one call (server)

1: the Wine server takes the path of a file it has just opened from its descriptor (fcntl F_GETPATH) instead of realpath, which checks the path one folder at a time (~0.5 ms a file on the device). Same resolved path; realpath stays the fallback. For games that open many files a second (Horizon Zero Dawn's shader cache in its menu). Off (default): realpath as before. Read at each launch; a later game of the same app run does not inherit it.

Type: On/off · Default: 0

env.MADEIRA_SRV_FGETPATH = 1
env.MADEIRA_STUCK_CHECK Text

MADEIRA_STUCK_CHECK=0 turns off the check that completes a store stuck across a 16 KB page.

Type: Text

env.MADEIRA_STUCK_CHECK = value
env.MADEIRA_TLS_X64 On/off

x64 fast path for TlsGetValue (kernelbase). Default off (experimental). 1: a TLS index below 64 is read in the x64 JIT code, without a round trip into native code. Read when a 64-bit program starts.

Type: On/off · Default: 0

env.MADEIRA_TLS_X64 = 1
env.MADEIRA_UNIX_EXIT_ROUTE Text

MADEIRA_UNIX_EXIT_ROUTE=0: a fatal unix-side error calls plain (shimmed) exit() again

Type: Text

env.MADEIRA_UNIX_EXIT_ROUTE = value
env.MADEIRA_VCRT_ARM64_AUTO On/off

ARM64 Visual C++ marker for Unreal games

Default on: a game with an Unreal Engine folder (Engine\Binaries or Engine\Extras) starts with env.MADEIRA_VCRT_ARM64_KEY = 1, so its bootstrap stops asking for the ARM64 Visual C++ redistributable (Satisfactory, Subnautica 2). A MADEIRA_VCRT_ARM64_KEY line in madeira.cfg or the game's config wins. 0: only such a line sets it. Read at launch.

Type: On/off · Default: 1

env.MADEIRA_VCRT_ARM64_AUTO = 1
env.MADEIRA_VCRT_ARM64_KEY Text

ARM64 Visual C++ runtime marker

Default empty: nothing written, except for an Unreal Engine game, which gets 1 automatically (env.MADEIRA_VCRT_ARM64_AUTO). 0 turns it off for a game. 1 (or a version such as 14.50.35717): the session has the ARM64 Visual C++ 2015-2022 redistributable's Installed marker (volatile keys; one the prefix has is left alone), for an Unreal bootstrap program that sees an ARM64 machine and stops asking for that redistributable (exit 0x2329). Read at session start.

Type: Text

env.MADEIRA_VCRT_ARM64_KEY = value
env.MADEIRA_VK_DIAGNOSTICS Text

No description written yet.

Type: Text

env.MADEIRA_VK_DIAGNOSTICS = value
env.MADEIRA_WOW64_PEB_SELF Text

Madeira wow64-peb-self: wow_peb is a session global that init_peb() sets for a 32-bit child and loader_ios.c temporarily clears while a 64-bit child runs unix_init_startup_info(). A 32-bit thread querying ProcessWow64Information during t...

Type: Text

env.MADEIRA_WOW64_PEB_SELF = value
env.MADEIRA_WOW_MAIN_FAIL_EXIT Text

This is the SESSION'S OWN program, not a child (a 32-bit program started on a device whose address space has no 4 GB window left). The pthread_exit() inside fatal_error() ends the boot thread (wine_process_thread) in the middle of __wine...

Type: Text

env.MADEIRA_WOW_MAIN_FAIL_EXIT = value
env.MADEIRA_X64_NTDLL_FILE Text

longest file name (characters) that is redirected sysx64 prefix (22) + IOS_X64_NAME_MAX + NUL

Type: Text

env.MADEIRA_X64_NTDLL_FILE = value
env._JAVA_OPTIONS Text

Java runtime options

Passed into the game's environment and read by a bundled Java runtime (e.g. -XX:-UseZGC to leave a garbage collector off that cannot map its heap here).

Type: Text

env._JAVA_OPTIONS = value

Windows, display & input

env.MADEIRA_ATOM_ARG On/off

Atoms in a 32-bit program's class and property names

Default on: a class or property name given as an atom that arrives offset by the 32-bit program's window base (inside its never-mapped first 64 KB) is taken as the atom, not read as a string pointer. 0 turns it off.

Type: On/off · Default: 1

env.MADEIRA_ATOM_ARG = 1
env.MADEIRA_CHILD_DESKTOP Text

Default on; 0 keeps a child without a desktop window, as before.

Type: Text

env.MADEIRA_CHILD_DESKTOP = value
env.MADEIRA_CLICK_FOCUS Text

0: a tap or click on an active window leaves its keyboard focus as it is

Type: Text

env.MADEIRA_CLICK_FOCUS = value
env.MADEIRA_DESKTOP Text

X-desktop probe: shared user32 .data means the 2nd GUI pseudo-process can resolve a NULL winproc (crash: blr NULL in call_window_proc). Log func + resolved procW for the first few calls per process.

Type: Text

env.MADEIRA_DESKTOP = value
env.MADEIRA_DESKTOP_FIT Text

DESKTOP FIT. A presenting window whose client area does not fit the wine desktop (a 1920x1080 window on a 1280x720 desktop) was cropped: only its top-left showed, under a title bar, which looked like a frozen, non-fullscreen game. Its Me...

Type: Text

env.MADEIRA_DESKTOP_FIT = value
env.MADEIRA_DESKTOP_TREE_DUMP Text

Desktop debugging: dump the full window tree every ~5s. Runs on this wine thread (valid TEB — the dump walks win32u internals). Off unless MADEIRA_DESKTOP_TREE_DUMP=1: it walked every window of every desktop session twelve times a minute...

Type: Text

env.MADEIRA_DESKTOP_TREE_DUMP = value
env.MADEIRA_DIRECT_CURSOR On/off

MADEIRA_DIRECT_CURSOR=0: no cursor is drawn on the game view, motion stays relative there and the pointer never locks by itself; the driver reports nothing.

Type: On/off · Default: 1

env.MADEIRA_DIRECT_CURSOR = 1
env.MADEIRA_DIRECT_WINDOW_SIZE Text

MADEIRA_DIRECT_WINDOW_SIZE=1: keep an opted-in presenting window's client at the selected resolution, including an engine resize after startup. Default off; desktop sessions and ordinary windowed games are unchanged.

Type: Text

env.MADEIRA_DIRECT_WINDOW_SIZE = value
env.MADEIRA_DISPLAY_SYNC On/off

Metal layer: keep display sync

A/B: 1 leaves the game's Metal layer in CoreAnimation's display-sync scheduling. Off (the default) sets the private displaySyncEnabled=false (the MeloNX pattern, 2026-07-03). For a title parked 18-72 ms a frame in nextDrawable with the display link honoured at 120 Hz, this is one of the two suspects for late drawables (the other: env.MADEIRA_PROMOTE_KICK).

Type: On/off · Default: 0

env.MADEIRA_DISPLAY_SYNC = 1
env.MADEIRA_DUMP_SURFACES Text

would be frame-to-frame change rather than corruption. That would have looked exactly like a finding. * So: a src dump arms wph_pair, and the very next present of any window dumps its surface under the SAME pair number. That is the tig...

Type: Text

env.MADEIRA_DUMP_SURFACES = value
env.MADEIRA_EXTENDED_MODES Text

1: list modes up to 4x the session default's pixels

Type: Text

env.MADEIRA_EXTENDED_MODES = value
env.MADEIRA_FONT_KEYS_REPAIR On/off

Repair the registry's font list

On (default): a session that found no fonts leaves the registry's Fonts key alone, stale external entries that name a font of C:\windows\Fonts are dropped, and the Windows directory's fonts get their Fonts values back (DirectWrite lists only those, so without them embedded browsers crash and dialogs draw no text). 0: upstream Wine's font key update. Read at session start.

Type: On/off · Default: 1

env.MADEIRA_FONT_KEYS_REPAIR = 1
env.MADEIRA_FOREGROUND_FIX Text

0: never make the game's main window foreground

Type: Text

env.MADEIRA_FOREGROUND_FIX = value
env.MADEIRA_FPS_CAP Number

Fixed frame cap (fps)

Unset (default): no cap beyond the FPS limit. 10-120: frames start at most N times a second for the whole session: a Direct3D 12 game's thread waits after each Present, a DXMT game's encode thread before each present (a timed kernel wait, not a spin). Any value, e.g. 20 or 24, unlike the FPS limit's 30/40/60; the lower of the two applies. While it is set, env.MADEIRA_FPS_GOV_MW is ignored. Needs the [xp] sampler (MADEIRA_PROBES not 0). Read at session start.

Type: Number

env.MADEIRA_FPS_CAP = value
env.MADEIRA_FPS_COUNT_HIDDEN Text

1: the FPS readouts count hidden windows' presents too (as before 2026-10-26)

Type: Text

env.MADEIRA_FPS_COUNT_HIDDEN = value
env.MADEIRA_FPS_GOV_BAND_MJ Number

Frame-cap governor: energy band (mJ)

Only with env.MADEIRA_FPS_GOV_MW set: how much energy the running balance may drift above or below the target before the cap moves one step (100-100000; unset or out of range: 1500). Smaller moves the cap sooner and more often. Read at session start.

Type: Number · Default: 1500

env.MADEIRA_FPS_GOV_BAND_MJ = 1500
env.MADEIRA_FPS_GOV_MAX Number

Frame-cap governor: highest cap (fps)

Only with env.MADEIRA_FPS_GOV_MW set: the highest frame cap the governor uses, the largest of 60, 40, 30, 24 and 20 at or below this value (20 when lower). Unset: 60. Read at session start.

Type: Number · Default: 60

env.MADEIRA_FPS_GOV_MAX = 60
env.MADEIRA_FPS_GOV_MIN Number

Frame-cap governor: lowest cap (fps)

Only with env.MADEIRA_FPS_GOV_MW set: the lowest frame cap the governor goes down to, the smallest of 60, 40, 30, 24 and 20 at or above this value, never above the highest cap. Unset: 20. Read at session start.

Type: Number · Default: 20

env.MADEIRA_FPS_GOV_MIN = 20
env.MADEIRA_FPS_GOV_MW Number

Hold CPU power with a frame cap (mW)

Unset (default): off. N: while the game presents, the process's CPU power ([xp]'s energy) is held at N mW on average by moving a frame cap between 60, 40, 30, 24 and 20 fps (at most one step per 3 s; held while nothing presents). Unlike env.MADEIRA_POWER_GOV_MW it moves no thread to the efficiency cores. Menus and loading at 3-4 W fill the budget after which iOS clamps the CPU; e.g. 1500 keeps a 60 fps menu near 30-40 fps. [fps-gov] lines every 10 s. env.MADEIRA_FPS_GOV_MIN / _MAX (20 / 60) bound the cap, _BAND_MJ (1500) is the energy the average may drift before it moves. Needs the [xp] sampler. Read at session start.

Type: Number

env.MADEIRA_FPS_GOV_MW = value
env.MADEIRA_FRAME_TIMES Text

0: no frame-time marks; the overlay's graph and 1% cells stay empty

Type: Text

env.MADEIRA_FRAME_TIMES = value
env.MADEIRA_FULLSCREEN_FOREGROUND Text

0: a full-screen window shown with activation is left to the foreground lock

Type: Text

env.MADEIRA_FULLSCREEN_FOREGROUND = value
env.MADEIRA_GAME_DIALOG_CURSOR On/off

Cursor over a game's launcher or message box

Default on. A game session draws no cursor: the finger is the pointer. While the game shows a launcher or message box, the arrow is drawn where the finger last touched (where the click lands) and goes away with the box. Tap the button itself to press it. 0: no cursor, as before. Desktop (Dock) sessions keep their own cursor.

Type: On/off · Default: 1

env.MADEIRA_GAME_DIALOG_CURSOR = 1
env.MADEIRA_GAME_INPUT_WAKE Text

Default on: a launcher / message box over a game takes taps and keys; 0 = off.

Type: Text

env.MADEIRA_GAME_INPUT_WAKE = value
env.MADEIRA_GAME_WINDOWS Text

Game-mode windows. Outside desktop mode a window got win32u's offscreen surface and its position never reached the app, so a launcher or a message box a game opens before (or instead of) its 3D window was drawn nowhere: a game's Play / O...

Type: Text

env.MADEIRA_GAME_WINDOWS = value
env.MADEIRA_GDI_SECTION_ALWAYS Text

upstream's anonymous allocation -- and any 32-bit program started LATER in such a session (a 64-bit launcher's 32-bit child, or the app's in-session launcher starting the 32-bit Steam client into an explorer desktop) kept the host table ...

Type: Text

env.MADEIRA_GDI_SECTION_ALWAYS = value
env.MADEIRA_GDI_SHARED_SECTION Text

was armed for 32-bit code when win32u initialised, so a 64-bit session kept upstream's anonymous allocation -- and any 32-bit program started LATER in such a session (a 64-bit launcher's 32-bit child, or the app's in-session launcher sta...

Type: Text

env.MADEIRA_GDI_SHARED_SECTION = value
env.MADEIRA_GL_BACKEND Text

With the GLES backend there is no desktop GL context, so make LOVE ask for OpenGL ES first. LOVE 11 checks this SDL hint (read from the environment) before trying desktop GL; SDL then creates the context through WGL_EXT_create_context_es...

Type: Text

env.MADEIRA_GL_BACKEND = value
env.MADEIRA_GL_COMPILE_TIMEOUT Text

seconds a Metal shader compile may take under Zink (default 20); then the shader fails and its draws are skipped. 0: no limit

Type: Text

env.MADEIRA_GL_COMPILE_TIMEOUT = value
env.MADEIRA_GL_DIR Text

Load OSMesa and prove Zink actually runs: a throwaway core-profile context must report the Zink renderer. Mesa quietly falls back to softpipe when Zink cannot start (no MoltenVK, missing Vulkan features), and a software rasterizer is not...

Type: Text

env.MADEIRA_GL_DIR = value
env.MADEIRA_GL_FPS_CAP Text

0: OpenGL games ignore the session's FPS limit, as before

Type: Text

env.MADEIRA_GL_FPS_CAP = value
env.MADEIRA_GL_PERF Text

0: no GL perf line (presents/s, flush-ms ...) and no stall reports

Type: Text

env.MADEIRA_GL_PERF = value
env.MADEIRA_GL_SHADER_CACHE Text

0: no Mesa shader disk cache for desktop OpenGL (Zink); every run converts and compiles all shaders again

Type: Text

env.MADEIRA_GL_SHADER_CACHE = value
env.MADEIRA_GL_VULKAN Text

Vulkan driver for Zink when madeira.cfg gl-vulkan is unset: moltenvk (default), kosmickrisp, or a .dylib name/path

Type: Text

env.MADEIRA_GL_VULKAN = value
env.MADEIRA_GPU_DEVICE Text

Windows' display adapter: PCI device id (hex)

With MADEIRA_GPU_VENDOR: the adapter's device id. Per game: Game details > Graphics card the game sees.

Type: Text

env.MADEIRA_GPU_DEVICE = value
env.MADEIRA_GPU_NAME Text

Windows' display adapter: name

The adapter name Windows reports with MADEIRA_GPU_VENDOR and MADEIRA_GPU_DEVICE; unset, the name of the PCI id. Per game: Game details > Graphics card the game sees.

Type: Text

env.MADEIRA_GPU_NAME = value
env.MADEIRA_GPU_VENDOR Text

Windows' display adapter: PCI vendor id (hex)

With MADEIRA_GPU_DEVICE: the display adapter win32u registers (EnumDisplayDevices, SetupAPI, the display driver key, D3DKMT), instead of Apple 106B:0001 or the RTX 3060 of Report an NVIDIA GPU. Per game: Game details > Graphics card the game sees, which sets DXGI and Direct3D 9 to the same card.

Type: Text

env.MADEIRA_GPU_VENDOR = value
env.MADEIRA_HIDDEN_LAYER_FPS Text

frames a second a hidden desktop window's Metal layer may present (default 10); 0 = no limit

Type: Text

env.MADEIRA_HIDDEN_LAYER_FPS = value
env.MADEIRA_HWINPUT On/off

MADEIRA_HWINPUT=0: no keyboard/mouse bridging, no pointer recognisers, no touch filter, no drawn cursor; the app behaves as it did before this file existed.

Type: On/off · Default: 1

env.MADEIRA_HWINPUT = 1
env.MADEIRA_INPUT_FOCUS On/off

MADEIRA_INPUT_FOCUS=0: keyboard and mouse reach the program whatever has focus (the program still gets nothing while the app is inactive: held input is released then).

Type: On/off · Default: 1

env.MADEIRA_INPUT_FOCUS = 1
env.MADEIRA_INPUT_FOREGROUND On/off

Bring the game to the front when no window is

Default off. iOS has no window manager: a game that shows its window without activating it and reads no XInput stays in the background, and Windows sends raw keyboard and mouse input only to the program in front (Horizon Zero Dawn ignored every key and tap). 1: while no window at all is in front, the game's main window is brought to the front when it polls its messages or a key or tap arrives. Never while another window is in front.

Type: On/off · Default: 0

env.MADEIRA_INPUT_FOREGROUND = 1
env.MADEIRA_KMT_ADAPTER On/off

D3DKMT adapter for the GPU (WDDM 3.1)

1: D3DKMTEnumAdapters2 lists the GPU DXGI and D3D12 report (same LUID) and D3DKMTQueryAdapterInfo answers like a WDDM 3.1 driver (driver version, caps, device ids, memory, performance data). Off (default): no adapter is listed, as before. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_KMT_ADAPTER = 1
env.MADEIRA_KMT_TRACE Text

The [vkmt] entry-point trace; MADEIRA_KMT_TRACE=0 turns it off.

Type: Text

env.MADEIRA_KMT_TRACE = value
env.MADEIRA_METAL_HUD_MAIN Text

1: Apple's Metal HUD only on the largest shown desktop window's Metal layer (its main layer), off on the other layers; default: Apple's own choice

Type: Text

env.MADEIRA_METAL_HUD_MAIN = value
env.MADEIRA_MOUSE_INVERT_Y On/off

No description written yet.

Type: On/off · Default: 1

env.MADEIRA_MOUSE_INVERT_Y = 1
env.MADEIRA_MOUSE_ROUTING On/off

Mouse routing and pointer-lock fixes

Default on. 0 restores the previous desktop cursor routing, mouse button callbacks, surface-touch handling and key-window-only pointer lock. Keyboard input and manual Ctrl+Alt+P remain available. Fully restart Madeira after changing this switch.

Type: On/off · Default: 1

env.MADEIRA_MOUSE_ROUTING = 1
env.MADEIRA_MOUSE_SWAP_BUTTONS On/off

No description written yet.

Type: On/off · Default: 1

env.MADEIRA_MOUSE_SWAP_BUTTONS = 1
env.MADEIRA_NAV_KEYS_E0 Text

Wine's own UI never noticed, because dialogs read the VK out of wParam. A GAME does notice: Unity reads the keyboard through raw input and DirectInput identifies keys by scan code (DIK_W is 0x11, not 'W'), so W/A/S/D were delivered, acce...

Type: Text

env.MADEIRA_NAV_KEYS_E0 = value
env.MADEIRA_OPENGL On/off

OpenGL through Mesa on D3D12

On: x64 games get Mesa's opengl32.dll (OpenGL 3.3 on D3D12, then Metal) when build/mesa-d3d12/build.sh has put it in the app. 0: Wine's builtin opengl32, which uses the native WGL OpenGL ES/Zink route. A game folder's own opengl32.dll still wins. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_OPENGL = 1
env.MADEIRA_PAD_KBM On/off

Availability of the mode. 0 removes the per-game choice; the physical pad then always feeds XInput.

Type: On/off · Default: 1

env.MADEIRA_PAD_KBM = 1
env.MADEIRA_PASTE_INTERVAL_MS Number

Clipboard typing interval (ms)

Default 10 ms between pasted characters. Range 1-100 ms; use a longer interval for games that miss fast text input. Enforced at delivery as well as queueing. Restart the session after changing it.

Type: Number · Default: 10

env.MADEIRA_PASTE_INTERVAL_MS = 10
env.MADEIRA_POINTER_ABSOLUTE On/off

MADEIRA_POINTER_ABSOLUTE=0: the program's cursor never follows the iOS pointer's position; all motion is relative.

Type: On/off · Default: 1

env.MADEIRA_POINTER_ABSOLUTE = 1
env.MADEIRA_POINTER_AUTOLOCK On/off

MADEIRA_POINTER_AUTOLOCK=0: the pointer locks only on request, not while the program hides its cursor (see AutoLock).

Type: On/off · Default: 1

env.MADEIRA_POINTER_AUTOLOCK = 1
env.MADEIRA_POINTER_HIDDEN_ABSOLUTE Text

MADEIRA_POINTER_HIDDEN_ABSOLUTE=1 (a game's own config): the program's cursor follows the iOS pointer's position even while it hides the Windows cursor, and the pointer never locks by itself. For a game that hides the cursor only to draw...

Type: Text

env.MADEIRA_POINTER_HIDDEN_ABSOLUTE = value
env.MADEIRA_POINTER_LOCK On/off

MADEIRA_POINTER_LOCK=0: the pointer is never locked and no lock button or chord is offered.

Type: On/off · Default: 1

env.MADEIRA_POINTER_LOCK = 1
env.MADEIRA_POINTER_LOCK_NOTICE On/off

MADEIRA_POINTER_LOCK_NOTICE=0: no notice when iPadOS refuses the pointer lock (see LockRefusedNotice).

Type: On/off · Default: 1

env.MADEIRA_POINTER_LOCK_NOTICE = 1
env.MADEIRA_POINTER_RAW_LOOK Text

MADEIRA_POINTER_RAW_LOOK=1 (a game's own config): while the program has raw mouse input registered at all, or a low-level mouse hook (DirectInput 7 and older), it reads motion: relative moves, its cursor is not drawn and the pointer lock...

Type: Text

env.MADEIRA_POINTER_RAW_LOOK = value
env.MADEIRA_POINTER_READER On/off

MADEIRA_POINTER_READER=0: how the program reads the mouse is ignored; a program that shows its cursor follows the pointer's position even while it reads raw or hooked mouse motion (see MouseReader).

Type: On/off · Default: 1

env.MADEIRA_POINTER_READER = 1
env.MADEIRA_PROMOTE_KICK On/off

Display link: commit a transaction per tick

experiment: 1 adds a one-pixel layer whose opacity alternates on every display-link tick, so each tick commits a CoreAnimation transaction. For a title parked 80 ms a frame in nextDrawable with the 120 Hz link armed: if the waits fall with this on, the compositor needed a transaction, not an intent.

Type: On/off · Default: 0

env.MADEIRA_PROMOTE_KICK = 1
env.MADEIRA_RESTORE_BORN_MINIMIZED Text

0: while a Dock start's census runs, a window first shown minimized stays minimized

Type: Text

env.MADEIRA_RESTORE_BORN_MINIMIZED = value
env.MADEIRA_RESTORE_BORN_MINIMIZED_LATE Text

0: a window first shown minimized after a Dock start's starting screen has ended stays minimized

Type: Text

env.MADEIRA_RESTORE_BORN_MINIMIZED_LATE = value
env.MADEIRA_SCREEN_H Text

MADEIRA_SCREEN_W/H: the virtual monitor's session default size, exported by the app before Wine starts (1024x768 when unset); a program's ChangeDisplaySettings changes the current size from there. MADEIRA_SCREEN_SRC names where the defau...

Type: Text

env.MADEIRA_SCREEN_H = value
env.MADEIRA_SCREEN_SRC Text

MADEIRA_SCREEN_W/H: the virtual monitor's session default size, exported by the app before Wine starts (1024x768 when unset); a program's ChangeDisplaySettings changes the current size from there. MADEIRA_SCREEN_SRC names where the defau...

Type: Text

env.MADEIRA_SCREEN_SRC = value
env.MADEIRA_SCREEN_W Text

MADEIRA_SCREEN_W/H: the virtual monitor's session default size, exported by the app before Wine starts (1024x768 when unset); a program's ChangeDisplaySettings changes the current size from there. MADEIRA_SCREEN_SRC names where the defau...

Type: Text

env.MADEIRA_SCREEN_W = value
env.MADEIRA_SURF_SENTINEL Text

them, and I reported the first as settled when the data did not support it. * Fix: after each flush, stamp every currently-zero pixel with a sentinel. That leaves NO zero pixels behind, so the next flush classifies every pixel with no bo...

Type: Text

env.MADEIRA_SURF_SENTINEL = value
env.MADEIRA_SURF_SEQ Text

Also drives MADEIRA_SURF_SEQ: bursts of N CONSECUTIVE frames, so the black regions that change every frame can be measured frame-to-frame offline. The 2s-throttled first/latest dump structurally cannot show that. Dirty rect goes in the f...

Type: Text

env.MADEIRA_SURF_SEQ = value
env.MADEIRA_TINY_WINDOW_FIX On/off

Size a tiny game window to the screen

Default off. 1: a window a swapchain presents into whose client area stays under 160x120 for 3 seconds while the swapchain draws 320x200 or more is sized to the virtual screen (at most twice per window). Needs a desktop (Dock) session. Logged as [tiny-win]. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_TINY_WINDOW_FIX = 1
env.MADEIRA_TOUCH_XINPUT Text

Touch controller as XInput player 1

No description written yet.

Type: Text

env.MADEIRA_TOUCH_XINPUT = value
env.MADEIRA_VDCFG_PATH On/off

QueryDisplayConfig lists the monitor's path

Default off: success with no path, as before. 1: QueryDisplayConfig returns the virtual monitor's one path (source and target mode, the desktop size) and DisplayConfigGetDeviceInfo names its source, target and adapter and answers its preferred mode and colour info, for a game that builds its fullscreen window from the paths (Unity, e.g. REPLACED: white screen).

Type: On/off · Default: 0

env.MADEIRA_VDCFG_PATH = 1
env.MADEIRA_VIRTUAL_MODE_SET Text

MADEIRA_VIRTUAL_MODE_SET=0: accept a listed mode without programming it -- the monitor keeps the session default size, as before this change.

Type: Text

env.MADEIRA_VIRTUAL_MODE_SET = value
env.MADEIRA_VK_BC_PROBE Text

No description written yet.

Type: Text

env.MADEIRA_VK_BC_PROBE = value
env.MADEIRA_VK_HOST_SUBOPTIMAL Text

The host surface can measure its size in other units than the client rect (an iOS CAMetalLayer reports points), so the host may call a swapchain suboptimal although it matches the window's client rect. The application cannot fix that: a ...

Type: Text

env.MADEIRA_VK_HOST_SUBOPTIMAL = value
env.MADEIRA_VMON_IDS Text

synthesized branch; DXGI_OUTPUT_DESC::DeviceName says the same), and one monitor under it, the virtual monitor, which has no source. Upstream's code gives a sourceless monitor the GDI name "WinDisc" -- Windows' name for a DISCONNECTED di...

Type: Text

env.MADEIRA_VMON_IDS = value
env.MADEIRA_VULKAN_LIBRARY Text

No description written yet.

Type: Text

env.MADEIRA_VULKAN_LIBRARY = value
env.MADEIRA_WINDOW_LINEAGE Text

1: report window lineage to the desktop compositor (off by default; this app's hook is a stub)

Type: Text

env.MADEIRA_WINDOW_LINEAGE = value
env.MADEIRA_WINPROC_HANDLE Text

No description written yet.

Type: Text

env.MADEIRA_WINPROC_HANDLE = value
env.MADEIRA_XCTEST_TYPING Text

True while a hardware keyboard delivers raw key events. The text bridge (MetalBackedView's UIKeyInput) receives the same presses from UIKit, so it stands aside while this is true instead of typing every key twice. An explicit test sessio...

Type: Text

env.MADEIRA_XCTEST_TYPING = value
env.MADEIRA_XINPUT On/off

Physical controllers (XInput)

physical and touch controller snapshots share the same serial publisher. Slot/profile/timer state belongs exclusively to queue. The app lifecycle and observer registration belong to the main actor. Guest readers use the C snaps...

Type: On/off · Default: 1

env.MADEIRA_XINPUT = 1

Steam & Dock

env. Text

env.NAME from madeira.cfg, then the process environment. "0" is off.

Type: Text

env. = value
env.MADEIRA_BACKGROUND_DOWNLOADS On/off

On iOS 26 and later, Steam downloads continue in the background as a continued-processing task that iOS shows with its progress. 0: only the short grace period, then a clean pause until Madeira is active again.

Type: On/off · Default: 1

env.MADEIRA_BACKGROUND_DOWNLOADS = 1
env.MADEIRA_BIG_PICTURE_DOCK_LIBRARIES On/off

Big Picture: every library Madeira lists

on (default): Big Picture's libraryfolders.vdf gets every library Madeira's Steam list reads: the Dock client's folder, the other C: libraries its libraryfolders.vdf names and the external drives' libraries. The log names each library with its number of install records. 0: only the Dock client's folder and the external drives .

Type: On/off · Default: 1

env.MADEIRA_BIG_PICTURE_DOCK_LIBRARIES = 1
env.MADEIRA_BIG_PICTURE_GPU On/off

Big Picture: draw the UI with the GPU

1 starts steam.exe without -cef-disable-gpu, so the web helper may draw with Chromium's ANGLE on the 32-bit D3D11 (DXMT) instead of the CPU. Off by default (software drawing, as before); a test switch.

Type: On/off · Default: 0

env.MADEIRA_BIG_PICTURE_GPU = 1
env.MADEIRA_BIG_PICTURE_LIBRARIES On/off

Big Picture: list Madeira's Steam games

on (default): before each Big Picture start, Big Picture's libraryfolders.vdf (config/ and steamapps/) gets Madeira's Steam library (the Dock client's folder) and the libraries on connected drives, beside the client's own entries, so the games Madeira installed show as installed. 0: the files are left alone.

Type: On/off · Default: 1

env.MADEIRA_BIG_PICTURE_LIBRARIES = 1
env.MADEIRA_BIG_PICTURE_PIN On/off

Big Picture: keep the installed 32-bit client

on (default): once Big Picture's folder holds the 32-bit client's web helper (bin/cef/cef.win7), steam.exe starts with -nobootstrapperupdate -skipinitialbootstrap, so it cannot move itself to the 64-bit client, whose CEF pools do not fit the address space. 0: Steam updates itself at every start, as before.

Type: On/off · Default: 1

env.MADEIRA_BIG_PICTURE_PIN = 1
env.MADEIRA_CEF_VERBOSE On/off

Steam web helper: verbose CEF log

on (default): steamwebhelper.exe gets --enable-logging=file --v=1 --log-severity=verbose, CEF's verbose file log. 0 (the Steam Big Picture list): Steam's own log level, which saves the UI threads the writes.

Type: On/off · Default: 1

env.MADEIRA_CEF_VERBOSE = 1
env.MADEIRA_DOCK On/off

env.MADEIRA_DOCK = 0 hides Dock. Without a built dockhost.exe it is hidden too.

Type: On/off · Default: 1

env.MADEIRA_DOCK = 1
env.MADEIRA_DOCK_AUTO_REVEAL On/off

0: a window that may need the user never reveals the desktop by itself (Show desktop still does)

Type: On/off · Default: 1

env.MADEIRA_DOCK_AUTO_REVEAL = 1
env.MADEIRA_DOCK_CEG On/off

The install record lists per-user executables: Dock asks Valve's client to prepare them before it launches. env.MADEIRA_DOCK_CEG = 0 never asks.

Type: On/off · Default: 1

env.MADEIRA_DOCK_CEG = 1
env.MADEIRA_DOCK_COMPACT_POOL On/off

Opt-in per launch: a 512 MB JIT pool instead of the standard one.

Type: On/off · Default: 0

env.MADEIRA_DOCK_COMPACT_POOL = 1
env.MADEIRA_DOCK_GAME_SCM Text

1: Wine's service manager in every Dock game session, 0: never; unset: only when the prefix registers an automatic-start service outside Windows

Type: Text

env.MADEIRA_DOCK_GAME_SCM = value
env.MADEIRA_DOCK_GAME_SCM_SERVER_SYNC On/off

0: a session that starts the service manager keeps madsync

Type: On/off · Default: 1

env.MADEIRA_DOCK_GAME_SCM_SERVER_SYNC = 1
env.MADEIRA_DOCK_HIDE_DESKTOP On/off

0: a Dock start's starting screen ends on the desktop's first frame, as before

Type: On/off · Default: 1

env.MADEIRA_DOCK_HIDE_DESKTOP = 1
env.MADEIRA_DOCK_IMAGE_MAP_GUARD On/off

While the loader loads Valve's client and its many imports, the emulator's image-map handler can commit a page of its own heap under its interval lock; the commit's notification then waits for that same lock and the host parks for good (...

Type: On/off · Default: 1

env.MADEIRA_DOCK_IMAGE_MAP_GUARD = 1
env.MADEIRA_DOCK_IMAGE_RETIRE On/off

Valve's client unloads DLLs while it starts and the loader can map a different DLL of the same size at the same address. The engine's opt-in image-retire switch (MADEIRA_JIT_IMAGE_RETIRE, off for every other session) gives that DLL fresh...

Type: On/off · Default: 1

env.MADEIRA_DOCK_IMAGE_RETIRE = 1
env.MADEIRA_DOCK_INSTALLERS On/off

0: Dock starts run no install-script programs

Type: On/off · Default: 1

env.MADEIRA_DOCK_INSTALLERS = 1
env.MADEIRA_DOCK_INSTALLER_REVEAL On/off

0: a one-time installer's dialog never reveals the desktop by itself

Type: On/off · Default: 1

env.MADEIRA_DOCK_INSTALLER_REVEAL = 1
env.MADEIRA_DOCK_INSTALL_CHOICE On/off

0: no per-game choice, every start runs what is pending

Type: On/off · Default: 1

env.MADEIRA_DOCK_INSTALL_CHOICE = 1
env.MADEIRA_DOCK_INSTALL_LAYOUT On/off

0: a session of one-time installs keeps the game's layout lines

Type: On/off · Default: 1

env.MADEIRA_DOCK_INSTALL_LAYOUT = 1
env.MADEIRA_DOCK_INSTALL_REGISTRY On/off

0: the install scripts' Registry values are not written

Type: On/off · Default: 1

env.MADEIRA_DOCK_INSTALL_REGISTRY = 1
env.MADEIRA_DOCK_INSTALL_SCM On/off

Installers expect a service manager, and a Dock session starts none before the host. With madsync, Wine's services.exe never answered its RPC clients in the fork's device runs, so the service step and then every installer waited; msiexec...

Type: On/off · Default: 1

env.MADEIRA_DOCK_INSTALL_SCM = 1
env.MADEIRA_DOCK_INSTALL_SEPARATE On/off

unset: only a game whose own lines hold an address-space layout line (env.MADEIRA_RDR2_VA_HOLD, env.MADEIRA_SC_PA_POOLS) runs its one-time installs in a session of their own and starts after a restart; every other game starts right after them in the same session. 1: always a session of their own; 0: never

Type: On/off

env.MADEIRA_DOCK_INSTALL_SEPARATE = 1
env.MADEIRA_DOCK_INSTALL_SERVER_SYNC On/off

Installers expect a service manager, and a Dock session starts none before the host. With madsync, Wine's services.exe never answered its RPC clients in the fork's device runs, so the service step and then every installer waited; msiexec...

Type: On/off · Default: 1

env.MADEIRA_DOCK_INSTALL_SERVER_SYNC = 1
env.MADEIRA_DOCK_OFFLINE_LOGON On/off

out a connection that cannot happen; - a note of the last online start in which Valve's client confirmed a licence and said the account can log on offline (the host's session-offline-ready=1), for the Game details mark. Steam's offline...

Type: On/off · Default: 1

env.MADEIRA_DOCK_OFFLINE_LOGON = 1
env.MADEIRA_DOCK_RESET_CLEAN On/off

0: Reset only forgets the records; installed files stay

Type: On/off · Default: 1

env.MADEIRA_DOCK_RESET_CLEAN = 1
env.MADEIRA_DOCK_STATUS On/off

0: the starting screen does not watch the host's result

Type: On/off · Default: 1

env.MADEIRA_DOCK_STATUS = 1
env.MADEIRA_DOCK_STEAM_RUN On/off

On by default: when a game in a Madeira Dock session asks Steam to start another game (steam.exe with steam://run/<App ID>, as Black Ops II's campaign does for Zombies), steam.exe is not started and Madeira starts that game when it is next opened. 0 lets steam.exe start as before (the full Steam client, which updates itself and stops at a black window in a Dock session).

Type: On/off · Default: 1

env.MADEIRA_DOCK_STEAM_RUN = 1
env.MADEIRA_DOCK_VULKAN_STANDIN On/off

0: a Vulkan loader an installer wrote stays in system32

Type: On/off · Default: 1

env.MADEIRA_DOCK_VULKAN_STANDIN = 1
env.MADEIRA_DOTNET_FUSION On/off

No description written yet.

Type: On/off · Default: 1

env.MADEIRA_DOTNET_FUSION = 1
env.MADEIRA_DOWNLOAD_NOTIFICATIONS On/off

Local notifications when a Steam download finishes, fails or pauses while Madeira is in the background (permission asked at the first download). 0: none, and no permission request.

Type: On/off · Default: 1

env.MADEIRA_DOWNLOAD_NOTIFICATIONS = 1
env.MADEIRA_INSTALL_DEFAULT_KEY On/off

The install scripts' programs of a game: its own folder (one level down) and the shared redistributables Steam keeps next to it, and how many scripts were read.

Type: On/off · Default: 1

env.MADEIRA_INSTALL_DEFAULT_KEY = 1
env.MADEIRA_INSTALL_SKIP_DIRECTX On/off

0: the DirectX redistributable runs too

Type: On/off · Default: 1

env.MADEIRA_INSTALL_SKIP_DIRECTX = 1
env.MADEIRA_INSTALL_SKIP_DOTNET On/off

0: .NET Framework setups run too

Type: On/off · Default: 1

env.MADEIRA_INSTALL_SKIP_DOTNET = 1
env.MADEIRA_ONBOARDING On/off

First-run Steam setup

env.MADEIRA_ONBOARDING = 0 (madeira.cfg or the environment) never opens setup and hides "Run setup again". On by default.

Type: On/off · Default: 1

env.MADEIRA_ONBOARDING = 1
env.MADEIRA_STEAM_ALLOW_CRASHPAD On/off

Steam web helper: allow its crash reporter

1 (the Steam Big Picture list) lets steamwebhelper.exe start exactly one kind of child, --type=crashpad-handler, with its command line unchanged; without it the 32-bit web helper ends itself at start (crash server failed to launch). Every other --type= child stays refused. Off (default): all are refused.

Type: On/off · Default: 0

env.MADEIRA_STEAM_ALLOW_CRASHPAD = 1
env.MADEIRA_STEAM_CDN_ROTATE On/off

On by default. env.MADEIRA_STEAM_CDN_ROTATE = 0 restores ordering the content servers by failure count first: one failure sends a server behind every server with none, so downloads narrow to the servers that have not failed. Read once, w...

Type: On/off · Default: 1

env.MADEIRA_STEAM_CDN_ROTATE = 1
env.MADEIRA_STEAM_CELL_ID Text

env.MADEIRA_STEAM_CELL_ID (madeira.cfg): a Steam cell id that replaces the one Steam picked from the sign-in. Unset or not a number: unchanged.

Type: Text

env.MADEIRA_STEAM_CELL_ID = value
env.MADEIRA_STEAM_CLOUD On/off

Whether Steam Cloud saves sync: Settings › Steam Cloud saves, kept in madeira.cfg as env.MADEIRA_STEAM_CLOUD (on unless it is 0; docs/STEAM_CLOUD.md). Turning it back on syncs the installed games at once.

Type: On/off · Default: 1

env.MADEIRA_STEAM_CLOUD = 1
env.MADEIRA_STEAM_CLOUD_AUTO On/off

env.MADEIRA_STEAM_CLOUD_AUTO = 0: compare only; nothing is copied either way without the user asking on the game's page.

Type: On/off · Default: 1

env.MADEIRA_STEAM_CLOUD_AUTO = 1
env.MADEIRA_STEAM_CLOUD_PLAY_CHECK On/off

Saves that need the user's choice (count).

Type: On/off · Default: 1

env.MADEIRA_STEAM_CLOUD_PLAY_CHECK = 1
env.MADEIRA_STEAM_CLOUD_QUIT On/off

A game cannot be closed from Madeira, so its saves otherwise reach the cloud only at the next app start. The session menu's "Upload saves and close Madeira" sends them now: the app takes the account back from the session's client, upload...

Type: On/off · Default: 1

env.MADEIRA_STEAM_CLOUD_QUIT = 1
env.MADEIRA_STEAM_CLOUD_REMOTECACHE On/off

env.MADEIRA_STEAM_CLOUD_REMOTECACHE = 0: Valve's client's remotecache.vdf is left as the client wrote it, as before SteamRemoteCache.

Type: On/off · Default: 1

env.MADEIRA_STEAM_CLOUD_REMOTECACHE = 1
env.MADEIRA_STEAM_DLC On/off

Owned DLC is listed and downloaded with its game (SteamDLC); off with env.MADEIRA_STEAM_DLC = 0, when downloads take no DLC as before.

Type: On/off · Default: 1

env.MADEIRA_STEAM_DLC = 1
env.MADEIRA_STEAM_LIBRARY On/off

Off with env.MADEIRA_STEAM_LIBRARY = 0, or without Madeira Dock (a downloaded game starts through it).

Type: On/off · Default: 1

env.MADEIRA_STEAM_LIBRARY = 1
env.MADEIRA_STEAM_SIGNIN On/off

env.MADEIRA_STEAM_SIGNIN = 0 hides the sign-in button.

Type: On/off · Default: 1

env.MADEIRA_STEAM_SIGNIN = 1
env.MADEIRA_STEAM_TRACE On/off

Logging for Steam sign-in. event lines are the always-on, low-volume record ([steam-signin]). They never contain tokens, passwords, Steam Guard codes, account names, Steam IDs or message payloads. trace lines are protocol-level detai...

Type: On/off · Default: 0

env.MADEIRA_STEAM_TRACE = 1
env.MADEIRA_STEAM_WORKSHOP On/off

Off with env.MADEIRA_STEAM_WORKSHOP = 0: no Workshop page or area.

Type: On/off · Default: 1

env.MADEIRA_STEAM_WORKSHOP = 1

Exceptions & threads

env.MADEIRA_ANON_CAS_FLUSH On/off

Atomic code patches go through the emulator

Default off: a compare-and-swap the game does on its own executable memory (a .NET runtime patching a stub it ran) is completed by the host. 1: it is handed to the emulator, which discards its translation of the page first, as in older builds. Slower. Logged as [anon-cas]. Read once per session.

Type: On/off · Default: 0

env.MADEIRA_ANON_CAS_FLUSH = 1
env.MADEIRA_APC_BUSY_QUEUE Text

wait in the server: check_wait returns STATUS_KERNEL_APC for any interruptible wait, and a fastsync wait parks in process for at most MADEIRA_FASTSYNC_CAP_US (2 ms) before it falls through to the server. It is not done when the process h...

Type: Text

env.MADEIRA_APC_BUSY_QUEUE = value
env.MADEIRA_APC_REQUEUE Text

On by default: an async I/O completion for a busy thread goes to a waiting thread of its process, if there is one, instead of failing the I/O. 0 always drops it again.

Type: Text

env.MADEIRA_APC_REQUEUE = value
env.MADEIRA_BUS_SYSCALL_FAULT Text

frame is inside the stack limits, and the process ended. A program that probes memory the IsBadReadPtr way (for example NtReadVirtualMemory on a guard page of its own stack) expects the call to fail with a status, not to die. * When a __...

Type: Text

env.MADEIRA_BUS_SYSCALL_FAULT = value
env.MADEIRA_CTX_CPU_AREA One of a list

Cross-thread GetThreadContext from the x64 snapshot

Another thread's GetThreadContext when the server has no control registers for it. Unset or 0 (default): off; the answer is the server's registers. 1 (upstream's opt-in): the control registers (Pc/Sp/Fp/Lr) from the thread's last exit from emulated code. 2: also the integer registers the caller asked for, and Cpsr 0, from the same snapshot; madeira-bcd's default behaviour, which every game list sets (Ghost of Tsushima's loading screen froze without it). The snapshot is where the thread last left emulated code, not where it is now: a context written back moves the thread back there.

Type: One of a list · Choices: , Off (default), 1, Control registers, 2, Control and integer registers

env.MADEIRA_CTX_CPU_AREA = 
env.MADEIRA_ECO_PRIO Text

1: under eco, a thread that raises itself to TIME_CRITICAL keeps user-interactive QoS; 2: HIGHEST and above; unset/0: off

Type: Text

env.MADEIRA_ECO_PRIO = value
env.MADEIRA_EXCL_LOGICAL Text

No description written yet.

Type: Text

env.MADEIRA_EXCL_LOGICAL = value
env.MADEIRA_FAULT_ESR_DIR Text

The data abort's ESR says whether the access wrote (WnR, bit 6). The encoding guess below calls the LSE atomics (LDADD, SWP, CAS...: an x86 lock xadd / xchg) reads, because they have bit 22 set, so a write was reported to the guest as a ...

Type: Text

env.MADEIRA_FAULT_ESR_DIR = value
env.MADEIRA_FAULT_GUARD_GUEST_RIP On/off

Fault guards tell FEX's invalid instructions apart

Default off. 1: the fault-storm guards also key an invalid-instruction delivery on the guest instruction FEX saved, so a program that steps over a long run of them in its own handler is not ended while it advances, and the 50-fault page breaker counts memory faults only. Logged as [redeliv] guest_rip. Read once per session.

Type: On/off · Default: 0

env.MADEIRA_FAULT_GUARD_GUEST_RIP = 1
env.MADEIRA_FAULT_GUARD_RATE On/off

Fault-storm guards end only a real storm

Default off. 1: a run of 2000 faults at one instruction ends the game only when it is dense (inside half a second) or presenting makes no progress, and the 5-repeat guard counts per thread within 5 ms; for a Unity title that throws managed exceptions through null-check traps while it keeps drawing. Read once per session.

Type: On/off · Default: 0

env.MADEIRA_FAULT_GUARD_RATE = 1
env.MADEIRA_FAULT_LOOP_GUEST_PROGRESS On/off

A run of breakpoints at different addresses is not a stuck thread

Default off. 1: the loop breaker (50 faults at one place end the thread) no longer counts int3 traps at different guest addresses as one stuck fault, though the emulator raises all of them from one host instruction. Logged as [fault-progress]. Read once per session.

Type: On/off · Default: 0

env.MADEIRA_FAULT_LOOP_GUEST_PROGRESS = 1
env.MADEIRA_FAULT_OPERANDS Text

No description written yet.

Type: Text

env.MADEIRA_FAULT_OPERANDS = value
env.MADEIRA_GUARD_SYSCALL_FAULT Text

No description written yet.

Type: Text

env.MADEIRA_GUARD_SYSCALL_FAULT = value
env.MADEIRA_GUEST_CTX Text

No description written yet.

Type: Text

env.MADEIRA_GUEST_CTX = value
env.MADEIRA_ILLEGAL_INSN_WORDS Text

rev=illegal-insn-words: an illegal-instruction exception (c000001d) raised from FEX code names a host pc inside the JIT pool. The report's [guest-insn] line cannot say what executed there (it needs a registered x64 text window, and the t...

Type: Text

env.MADEIRA_ILLEGAL_INSN_WORDS = value
env.MADEIRA_JIT_DUMP Text

1: write Documents/fex-jit-dump.bin (the JIT pool, sparse) on the first mach UNHANDLED / SIGILL ; default 0.

Type: Text

env.MADEIRA_JIT_DUMP = value
env.MADEIRA_MACH_ALIGN_FAULT Text

No description written yet.

Type: Text

env.MADEIRA_MACH_ALIGN_FAULT = value
env.MADEIRA_NO_HEAL Text

Healing default-ON since 2026-07-07: the patcher now rewrites ONLY IAT/delay-IAT slots (parsed from each pool copy's PE headers), so the 2026-07-04 breakage class — arm64x metadata slots whose consumers need PE VAs for identity/range com...

Type: Text

env.MADEIRA_NO_HEAL = value
env.MADEIRA_ODD_VTABLE_REPAIR Text

mov rax, [rcx] ; loads RAX = klass | 1 mov rdx, [rax + 0x210] ; 1-byte misaligned read -> (slot1 >> 8) | (slot2 << 56) call [rax + 0x208] ; 1-byte misaligned read -> (slot0 >> 8) | (slot1 << 56) while bit 0 is set. The shifted read place...

Type: Text

env.MADEIRA_ODD_VTABLE_REPAIR = value
env.MADEIRA_POOL_NOEXEC_GIVEUP Text

code again (the [pool-poison] class). When the faulting code is the process's own ntdll copy, the exception dispatcher sits on the same dead pages, so delivering the fault faults again at the dispatcher, forever: device log 81, tw...

Type: Text

env.MADEIRA_POOL_NOEXEC_GIVEUP = value
env.MADEIRA_PROCESS_APC_QUEUE Text

duplicated that handle, so the action returned 5 and the install ended with 1603. * Instead queue it on the process's first live thread; that thread runs system APCs at its next interruptible server wait (check_wait returns STATUS_KERNEL...

Type: Text

env.MADEIRA_PROCESS_APC_QUEUE = value
env.MADEIRA_RECOVERY_LOG_SAMPLE On/off

Sample routine instruction recovery logs

Default off. 1: of FEX's records about each recovered invalid instruction (C000001D) only the first 16 and every 1024th are kept, and of the shared-trap ILL reports the first 8 and every 1024th; only the log changes. For a game that recovers thousands a second. Read before guest threads start.

Type: On/off · Default: 0

env.MADEIRA_RECOVERY_LOG_SAMPLE = 1
env.MADEIRA_REDELIV_CHILD_ONLY On/off

A fault storm in a helper program ends only that program

Default on: when the fault-storm guard gives up on a thread of a program the session started (a launcher's helper), that program ends and the app keeps running; the session's first program keeps the old ending. 0: the whole app ends for every storm, as before.

Type: On/off · Default: 1

env.MADEIRA_REDELIV_CHILD_ONLY = 1
env.MADEIRA_REDELIV_VPROTECT Text

A protection change between two deliveries (FEX's self-modifying-code cycle: unprotect, recompile, protect again) is real progress. Tag redeliv_guest_rip with the protection sequence number so the consecutive counter below starts a new r...

Type: Text

env.MADEIRA_REDELIV_VPROTECT = value
env.MADEIRA_SRCWATCH Text

competing for it means whichever runs first silently wins and the other is never armed at all — a probe that reports nothing while looking healthy. There are now two subjects: * "render" — win32u's dibdrv_PutImage, Chromium's SOURCE bitm...

Type: Text

env.MADEIRA_SRCWATCH = value
env.MADEIRA_SRCWATCH_ROWS Text

1. TARGETING. Arming the whole 1.2MB bitmap spreads a 400-attribution budget across ~76 pages, so the clear (which touches EVERY page first) dominates and the content painters — the writers that would name a displaced band — stay invisib...

Type: Text

env.MADEIRA_SRCWATCH_ROWS = value
env.MADEIRA_SRW_HANG_DIAG_S Number

Diagnostic: 32-bit SRW-lock hangs

a 32-bit thread that has waited this many seconds without a timeout for an SRW lock held by shared owners has every 32-bit thread of its process logged once ([srw-hang]: x86 registers, EBP chain, module-resolved stack words), so the holders are named. Logs 116-119: Steam's 32-bit web helper stopped at start that way. 0: off.

Type: Number · Default: 30

env.MADEIRA_SRW_HANG_DIAG_S = 30
env.MADEIRA_SRW_HANG_KILL_S Number

End a process stuck on an SRW lock

unset (default): never. N: once a 32-bit thread has waited N seconds for an SRW lock as above, the wineserver ends its process, as TerminateProcess from another process would, so a parent that restarts its helper gets a new one (Steam restarts its web helper). At most 3 per app run. The Steam Big Picture list sets 40.

Type: Number

env.MADEIRA_SRW_HANG_KILL_S = value
env.MADEIRA_TASK_EXC Text

Opt-out only: this strictly removes a dependency on a port we do not own, so it defaults ON. MADEIRA_TASK_EXC=0 restores the pre- behaviour for a same-build A/B against the ~54s stall.

Type: Text

env.MADEIRA_TASK_EXC = value
env.MADEIRA_THREADNAME_SWALLOW Text

healthy, over a printf. On Windows with no debugger attached this is a no-op. * So swallow it and continue, exactly as the DBG_CONTINUE path above does. This does not paper over the stuck unwind (task #38) -- it stops a benign event from...

Type: Text

env.MADEIRA_THREADNAME_SWALLOW = value
env.MADEIRA_THREAD_QOS Text

end = 0;

Type: Text

env.MADEIRA_THREAD_QOS = value
env.MADEIRA_THREAD_REAP_CHECKED On/off

Check the previous exited thread before freeing it

on (default): a thread that exits frees the previous exited thread's stacks only after finding that thread, by its process, thread id and pthread, in the live TEB list (the hand-off env.MADEIRA_EA_CEF = 1 already used). 32-bit processes started one after another can get the same window and TEB addresses; the unchecked hand-off then made a new thread free its own kernel stack at exit and hang there holding the memory lock (testers' log, 2026-10-31: a launcher installer's second VC++ redistributable, the installer waiting on that thread forever). 0: the upstream hand-off, unless MADEIRA_EA_CEF = 1.

Type: On/off · Default: 1

env.MADEIRA_THREAD_REAP_CHECKED = 1
env.MADEIRA_THREAD_REUSE Text

On by default. MADEIRA_THREAD_REUSE=0 never gives a full thread registry's exited or purged entries to new threads (a session again registers 512 threads at most).

Type: Text

env.MADEIRA_THREAD_REUSE = value
env.MADEIRA_THREAD_START_PE_VA Text

No description written yet.

Type: Text

env.MADEIRA_THREAD_START_PE_VA = value
env.MADEIRA_TLSWATCH Text

OPT-IN. The diagnosis is closed ( fixed the TLS-slot aliasing), but this stayed armed on every new thread, write-protecting its 16 KB TLS page. A UE 5.4 worker's plain TLS-slot store compiles to a store-release (stlr), ...

Type: Text

env.MADEIRA_TLSWATCH = value
env.MADEIRA_WATCH_CHASE Text

predecessor fragment's tail). the first version kept six candidates and stopped on more; here a fragment every six bytes put six neighbours' entries in the window before the writer's own, so nothing was followed. MADEIRA_WATCH_CH...

Type: Text

env.MADEIRA_WATCH_CHASE = value
env.MADEIRA_WATCH_WRITES Text

No description written yet.

Type: Text

env.MADEIRA_WATCH_WRITES = value
env.MADEIRA_WIN_THREAD_PRIORITY Text

madeira-bcd: thread priority keeps the pthread QoS (tools/patch-wine-thread-qos.py). Below the realtime band the Mach precedence/throughput/latency policies only demote a USER_INTERACTIVE guest thread onto the efficiency cores.

Type: Text

env.MADEIRA_WIN_THREAD_PRIORITY = value
env.MADEIRA_WOW_AFFINITY32 On/off

32-bit thread group affinity

on (default): a 32-bit program's GROUP_AFFINITY thread attribute (12 bytes, a 32-bit mask) is decoded field by field when the thread is created; read as the 16-byte native struct, NtCreateThreadEx failed with c000000d and a 32-bit Chromium's thread pool threw. 0: read as before.

Type: On/off · Default: 1

env.MADEIRA_WOW_AFFINITY32 = 1
env.MADEIRA_WOW_CHILD_PEB Text

A thread of a child process in its own guest window gets THAT process's PEB32 (the page after its PEB), not the main process's wow_peb, when its argument is the PEB. MADEIRA_WOW_CHILD_PEB=0 always passes wow_peb as before.

Type: Text

env.MADEIRA_WOW_CHILD_PEB = value
env.MADEIRA_WOW_LOW_RIP_GUEST Text

No description written yet.

Type: Text

env.MADEIRA_WOW_LOW_RIP_GUEST = value
env.MADEIRA_WOW_REAP_DEAD Text

[wow-reap]: a thread of an EXITED process that is held suspended (the [zombie] rule's or ios_thread_registry_end_dead_range's fallback when thread_terminate is refused) never runs again, so it cannot touch the window: it does not hold it...

Type: Text

env.MADEIRA_WOW_REAP_DEAD = value
env.MADEIRA_WX Text

OFF BY DEFAULT. This optimization has known stale-translation and address-reuse hazards and has already produced deterministic crashes in two builds; silent corruption on a fresh install would be worse than a clean crash, and a ki...

Type: Text

env.MADEIRA_WX = value
env.MADEIRA_X18_SIGNED_LOAD Text

ios_mach_exception_thread). It decoded the zero-extending unsigned-offset loads (LDR X, LDR W, LDRB, LDRH) but not the sign-extending ones, so the access was declined as "UNRECOGNIZED" and the thread died: ldrsw x28, [x18, #0x180c] (0x...

Type: Text

env.MADEIRA_X18_SIGNED_LOAD = value

x86 emulation (FEX)

env.MADEIRA_ARENA_TEST Text

No description written yet.

Type: Text

env.MADEIRA_ARENA_TEST = value
env.MADEIRA_BLOCK_RING Text

the block-entry ring, when MADEIRA_BLOCK_RING is set (32 KB per thread, never freed).

Type: Text

env.MADEIRA_BLOCK_RING = value
env.MADEIRA_CALLRET_RESET_RATE Text

MADEIRA: rate-limit the call-ret reset that follows a code invalidation. * On the iOS host nothing reads the stack's contents: the RET shortcut (BranchOps.cpp, ) and the EnterEC return (Dispatcher.cpp) are compiled out, so a skipped...

Type: Text

env.MADEIRA_CALLRET_RESET_RATE = value
env.MADEIRA_DIAG Text

MADEIRA THIS ESTIMATOR IS DIAGNOSTIC AND IT WAS NOT FREE. * It runs on EVERY C++ CompileBlock dispatch -- which is every inline-L1 miss, measured at 42-65 k/s in [fex-stats] -- and every iteration does a bus-locked RMW on one of t...

Type: Text

env.MADEIRA_DIAG = value
env.MADEIRA_EC_FFS_BYPASS Text

The load is what keeps the tripwire reference alive through -O2; the value itself is only interesting as proof on the device that the assembler and the compiler agreed about FEX_IOS_HOST for this binary.

Type: Text

env.MADEIRA_EC_FFS_BYPASS = value
env.MADEIRA_EC_POOL_FASTOUT Text

the in-pool fast-out in ExitFunctionEC. Read here so it is set before the first BTCpu64IosAddAliasMapping can publish a span; with it off the span stays 0 and Module.S takes the pre- path.

Type: Text

env.MADEIRA_EC_POOL_FASTOUT = value
env.MADEIRA_EXEC_FAULT_CODE Text

A page-fault raised by an explicit break in JIT code is always an execute fault

Type: Text

env.MADEIRA_EXEC_FAULT_CODE = value
env.MADEIRA_FEX_AVX Text

iOS-Madeira: MADEIRA_FEX_AVX=2, AVX without AVX2 (see HideAVX2 in CPUID.h). Exactly "2"; "1" and unset are unchanged.

Type: Text

env.MADEIRA_FEX_AVX = value
env.MADEIRA_FEX_BRANCH_HISTORY Text

Recorder emitted only for this executable, before CTX/JIT creation.

Type: Text

env.MADEIRA_FEX_BRANCH_HISTORY = value
env.MADEIRA_FEX_CALLRET_ELIDE On/off

64-bit JIT without the call-return shadow stack

Default on. The 64-bit (ARM64EC) JIT no longer keeps FEX's call-return shadow stack, which nothing reads on iOS: 9 instructions less per guest CALL and per RET, and linked calls become bl, so the CPU's return predictor follows guest calls. 0: the stack as before. Read when a program starts.

Type: On/off · Default: 1

env.MADEIRA_FEX_CALLRET_ELIDE = 1
env.MADEIRA_FEX_EC_BITMAP_CACHE On/off

Native-code check with the thread's bitmap pointer

Default on. The 64-bit JIT's dispatcher tests the native-code bitmap through a pointer kept in the thread's state instead of walking TPIDRRO_EL0, the TEB and the PEB: 4 instructions less on every call into a system DLL through its import table. 0: the walk as before. Read when a program starts.

Type: On/off · Default: 1

env.MADEIRA_FEX_EC_BITMAP_CACHE = 1
env.MADEIRA_FEX_EC_EXIT_LEAN On/off

Lean exit from the JIT into native code

Default on while AFP is off (the default). Calls from the 64-bit JIT into native (ARM64EC) code use a shorter stub: no FPCR read, the CPU area and suspend doorbell from the thread's state, the call counted per thread instead of with an atomic, and the alias lookup starting at the thread's own last hit; 31 instructions instead of 44. [xp-api] x64->EC rates lag by under 64 calls per thread. 0: ExitFunctionEC as before. Read when a program starts.

Type: On/off · Default: 1

env.MADEIRA_FEX_EC_EXIT_LEAN = 1
env.MADEIRA_FEX_EC_RET On/off

Returns from native code through the return predictor

Default on. A guest call into native (ARM64EC) code leaves the JIT with BLR and its return comes back with RET after an L1 lookup (10 instructions instead of 22), so the CPU's return-address predictor stays in step with the guest's calls. 0: BR and the dispatcher loop as before. Read when a program starts.

Type: On/off · Default: 1

env.MADEIRA_FEX_EC_RET = 1
env.MADEIRA_FEX_EC_RET_DIRECT On/off

Returns from native code straight into the JIT

Default on. When a native (ARM64EC) function returns to the game's x64 code, the return enters the 64-bit JIT at once instead of testing the native-code bitmap first; the JIT's dispatcher already tests every address it has no translation for. 11 instructions less per return from a system DLL. 0: the test as before. Read when a program starts.

Type: On/off · Default: 1

env.MADEIRA_FEX_EC_RET_DIRECT = 1
env.MADEIRA_FEX_FAIL_CALLRET Text

MADEIRA_FEX_FAIL_CALLRET=threadstate:N fails the Nth thread-state allocation, so this containment path can be proven rather than assumed -- it only occurs naturally once the band is exhausted.

Type: Text

env.MADEIRA_FEX_FAIL_CALLRET = value
env.MADEIRA_FEX_PRELOADED_IMAGES On/off

FEX: record images loaded before it starts

on (default): when FEX starts in a 64-bit process it records the code sections of every image already loaded (kernel32, kernelbase, ucrtbase are mapped for it before its notifications work). Before, their x64 export thunks were not known as code: a 64-bit x64 program's call into one ended it with c0000005 (log 120: the DirectX redistributable's x64 helper, at its first kernel32 call). 0: as before.

Type: On/off · Default: 1

env.MADEIRA_FEX_PRELOADED_IMAGES = 1
env.MADEIRA_FEX_SMC_FASTPATH Text

madeira-bcd: smc-store-fastpath v1. MADEIRA_FEX_SMC_FASTPATH=0 restores the locked path.

Type: Text

env.MADEIRA_FEX_SMC_FASTPATH = value
env.MADEIRA_FLUSH_OWN_LOCK On/off

FEX: skip its own code flushes under the invalidation lock

[flush-own-lock]: on (default): when FEX flushes its own translated code (a block unlinked while code is being invalidated) and wine passes the flush back to it, FEX returns at once instead of waiting for its thread lock. Before, that wait and a write fault on another thread waited on each other forever (PvZ Fusion with MelonLoader froze 24 to 100 s in, Test 8 logs, Nov 10). 0: the old wait. Read once per process.

Type: On/off · Default: 1

env.MADEIRA_FLUSH_OWN_LOCK = 1
env.MADEIRA_INVALIDATION_NESTED Text

MADEIRA: CodeInvalidationMutex is not recursive. When this thread already write-owns it, a second exclusive lock parks the thread behind itself, and every other thread queues behind it for good (log 56: one thread waiting on the lock it ...

Type: Text

env.MADEIRA_INVALIDATION_NESTED = value
env.MADEIRA_IRCAP_MODULE Text

arm the targeted IR capture (PassManager.cpp) once the module that owns the instruction under investigation is mapped. Module + RVA come from the environment so chasing a different miscompile never needs a rebuild; the defaults ar...

Type: Text

env.MADEIRA_IRCAP_MODULE = value
env.MADEIRA_IRCAP_RVA Text

arm the targeted IR capture (PassManager.cpp) once the module that owns the instruction under investigation is mapped. Module + RVA come from the environment so chasing a different miscompile never needs a rebuild; the defaults ar...

Type: Text

env.MADEIRA_IRCAP_RVA = value
env.MADEIRA_IR_TOPO Text

iOS-Madeira name the pass that breaks the intrusive node list. DFE and RA both detect corruption at their own entry, but by then the damage is upstream and anonymous. This sweeps every block after every pass and reports the FIRST ...

Type: Text

env.MADEIRA_IR_TOPO = value
env.MADEIRA_IR_TOPO_MIN Text

only sweep BIG functions. swept every block after every pass on every compile and that alone stalled the renderer -- it spent as much time in ValidateBlockTopology as in the whole x86 decoder, and Steam never reached the UI...

Type: Text

env.MADEIRA_IR_TOPO_MIN = value
env.MADEIRA_LOW_RIP_FAULT Text

A null native return target loses the guest fault location and bypasses JIT exception reconstruction. Let the executable-range checked decoder emit its normal NoExecOp instead, just as for any other unmapped address.

Type: Text

env.MADEIRA_LOW_RIP_FAULT = value
env.MADEIRA_NO_DFE Text

iOS-Madeira TARGETED A/B for the post-login hang. The renderer thread was sampled 9x at 97-100% CPU inside DeadFlagCalculationEliminination while everything else idled and Steam presented no further frames. FEX_O0 is the wro...

Type: Text

env.MADEIRA_NO_DFE = value
env.MADEIRA_ORDERED_PROFILE Text

see IosOrderedProfileReason. Applied before CreateNewContext reads the options.

Type: Text

env.MADEIRA_ORDERED_PROFILE = value
env.MADEIRA_SMC_HOT_PAGE Text

MADEIRA: hot SMC pages (InvalidationTracker::EnableHotSMCPages). MADEIRA_SMC_HOT_PAGE: unset = 64 write faults within a second, 0 = off (every write to a code page invalidates it), N = threshold.

Type: Text

env.MADEIRA_SMC_HOT_PAGE = value
env.MADEIRA_STRICT_SPLITLOCK Text

MADEIRA: StrictInProcessSplitLocks defaults ON for 32-bit guests. * An x86 LOCK op on a word that crosses a 16-byte boundary faults on this host and FEX emulates it as two separate half-width CASes. Without the strict mode two threads do...

Type: Text

env.MADEIRA_STRICT_SPLITLOCK = value
env.MADEIRA_WINEMONO_BRIDGE Text

FEX's Mono backpatcher bridge . On by itself for Wine Mono, 32- and 64-bit (/); for the 32-bit runtime in a guest window it also turns SMC detection off once the backpatcher is found . 0 keeps it off.

Type: Text

env.MADEIRA_WINEMONO_BRIDGE = value
env.MADEIRA_WOW_SYSCALL_SWEEP Text

No description written yet.

Type: Text

env.MADEIRA_WOW_SYSCALL_SWEEP = value
ignore-volatile-metadata On/off

FEX: x86 ordering for the whole image

Default off. 1: an x64 image's PE volatile metadata (MSVC /volatileMetadata) is cleared when it is mapped, so FEX orders every instruction of it by its TSO settings instead of only the listed ones. Slower; for testing memory-ordering bugs. Logged as [fex-vmeta]. Read at session start.

Type: On/off · Default: 0

ignore-volatile-metadata = 1

Wine server

env.MADEIRA_CLIP_NOTIFY_ALWAYS Text

1: notify the foreground thread on every ClipCursor, as before

Type: Text

env.MADEIRA_CLIP_NOTIFY_ALWAYS = value
env.MADEIRA_CTX_FP Text

MADEIRA_CTX_FP=0: a cross-thread GetThreadContext returns zeroed vector registers, as before. madeira.cfg (and the game's own lines) are read first: this server starts before the app exports env.* lines and runs again for the ne...

Type: Text

env.MADEIRA_CTX_FP = value
env.MADEIRA_CTX_FRAME Text

a live mirror, which is why four of five stalled threads reported rip=0. * Selector mirrors is_inside_syscall() exactly: kernel_stack <= sp <= syscall_frame. NOT "native pc is not EC" -- FEX JIT code is also non-EC but its frame may be s...

Type: Text

env.MADEIRA_CTX_FRAME = value
env.MADEIRA_DEAD_RELEASE Text

getenv once, not per release

Type: Text

env.MADEIRA_DEAD_RELEASE = value
env.MADEIRA_ILONLY_WOW64 Text

Kill switch, read once: 0 turns the check off.

Type: Text

env.MADEIRA_ILONLY_WOW64 = value
env.MADEIRA_INPUT_DESKTOP_LOG Text

No description written yet.

Type: Text

env.MADEIRA_INPUT_DESKTOP_LOG = value
env.MADEIRA_KEEP_INPUT_DESKTOP Text

Read again when more than a second old (as ios_ctx_fp_enabled): this server runs again for the next session in the same app run, and Just Cause 2's own list sets env.MADEIRA_KEEP_INPUT_DESKTOP = 0 for its session only, so a value kept fr...

Type: Text

env.MADEIRA_KEEP_INPUT_DESKTOP = value
env.MADEIRA_LOCAL_PROCESS_WRITE Text

Keep local writes disabled by default: enabling them globally regressed Steam. Explicitly opt in only for pseudo-processes in this Unix task. The request handler has already checked PROCESS_VM_WRITE rights.

Type: Text

env.MADEIRA_LOCAL_PROCESS_WRITE = value
env.MADEIRA_REAL_SUSPEND Text

Read on every call: the app sets it per session (a game's "Pause threads fully" switch, BCDLaunch.realSuspend), and this server runs again in the same process for the next session of the app run. Logged when it changes.

Type: Text

env.MADEIRA_REAL_SUSPEND = value
env.MADEIRA_REGFLUSH_SAVE Text

MADEIRA_REGFLUSH_SAVE=0: RegFlushKey does nothing again; the registry is saved periodically and at exit

Type: Text

env.MADEIRA_REGFLUSH_SAVE = value
env.MADEIRA_REPLACE_READONLY_LINK Text

On by default: an overwrite (supersede, overwrite, overwrite-if) through a link to a read-only file replaces the link with a new file. 0 fails it with access denied.

Type: Text

env.MADEIRA_REPLACE_READONLY_LINK = value
env.MADEIRA_SRV_DIRECT Text

Run simple server requests on the calling thread

Default off. 1: the Wine server's simplest requests (opening files and their descriptors, closing handles, mappings looked up, registry keys and values, events, semaphores, mutexes, completion ports) run on the thread that asks, under the server's lock, instead of a round trip through a pipe to the server thread: no thread switches, and the work runs on the asking thread's core. 2: waits (select), timers and set_cursor too. Every other request goes through the pipe as before. Horizon Zero Dawn's menu sends ~7000 requests a second. Read at each launch.

Type: Text · Default: 0 · Choices: , Off (default), 1, Files, handles, registry, events, semaphores, 2, Also waits, timers and the cursor

env.MADEIRA_SRV_DIRECT = 0
env.MADEIRA_SRV_DOORBELL Text

0: read every client fd on every pass, as before

Type: Text

env.MADEIRA_SRV_DOORBELL = value
env.MADEIRA_SRV_ECO_FOLLOW On/off

Server thread follows ECO

Default off. 1: while ECO is on, the Wine server thread runs at utility QoS (ECO's default class) instead of user-interactive, so it moves to the efficiency cores with the game's threads, and back when ECO goes off. In Horizon Zero Dawn's menu with eco = 1 the server was the only thread left on a performance core (0.54 cores at ~3.9 GHz). Server requests may take longer. Read at each launch.

Type: On/off · Default: 0

env.MADEIRA_SRV_ECO_FOLLOW = 1
env.MADEIRA_SRV_FD_SOCKET On/off

File descriptors through the process socket

Kill switch, default 0: a file's descriptor comes back in the server's get_handle_fd reply (a copy the server makes; it shares this process's descriptor table), the same descriptor without a sendmsg, a recvmsg, an fcntl and two server log lines per file. 1: through the process socket, as before. Read once per app run.

Type: On/off · Default: 0

env.MADEIRA_SRV_FD_SOCKET = 1
env.MADEIRA_SRV_FULLSCAN_MS Text

ms between reads of every client fd with the doorbell on (default 10)

Type: Text

env.MADEIRA_SRV_FULLSCAN_MS = value
env.MADEIRA_SRV_IDLE_US Number

Server loop's longest sleep (us)

Default 1000 (1 ms, as before); 100 to 50000. Requests and timers wake the Wine server at once; only its socket polls and fd scans wait for this tick, so a longer one means fewer server wake-ups while idle (1000 a second at the default) and slower readiness of network sockets and pipes. Mostly useful with env.MADEIRA_SRV_DIRECT. Read at each launch.

Type: Number · Default: 1000

env.MADEIRA_SRV_IDLE_US = 1000
env.MADEIRA_SRV_LOG_ALL On/off

Every per-descriptor server log line

Kill switch, default 0: the Wine server's add_poll_user and send_client_fd log lines (one per opened file or descriptor sent, each a formatted write to the log file on the server thread) are written for their first 64 and then every 1000th; a failed send is always written. 1: every line, as before. Read at each launch.

Type: On/off · Default: 0

env.MADEIRA_SRV_LOG_ALL = 1
env.MADEIRA_SRV_NOSEM Text

zero, semaphore_timedwait returns instantly forever, and the loop stops sleeping — measured 2,935 iter/s against a 1 ms floor that caps it at ~1,000/s. * This gate changes ONLY the wait mechanism. sleep_ns is computed identically a...

Type: Text

env.MADEIRA_SRV_NOSEM = value
env.MADEIRA_SRV_POLL_US Text

us between socket polls and fd scans with the doorbell on (default 1000, 0 every pass)

Type: Text

env.MADEIRA_SRV_POLL_US = value
env.MADEIRA_SRV_WAKE_COALESCE Text

0: one wake signal per request, as before

Type: Text

env.MADEIRA_SRV_WAKE_COALESCE = value
env.MADEIRA_STORAGE_DEVICE Text

0: no \\.\\PhysicalDrive0 (the prefix disk's capacity)

Type: Text

env.MADEIRA_STORAGE_DEVICE = value
env.MADEIRA_STUCK_WAIT_SECS Text

No description written yet.

Type: Text

env.MADEIRA_STUCK_WAIT_SECS = value
env.MADEIRA_TIMER_FAIRNESS On/off

Timers run while a window keeps repainting

Default on. A thread gets its paint messages before its timers, so a window that invalidates itself while it paints starved every timer of that thread for good: the Rockstar Games Launcher installer, whose status text and finish page run on a timer, stayed at "Preparing to Install..." after its work was done. A timer that has waited 100 ms now goes before such a paint. 0: the strict order, as before. Read once per app run.

Type: On/off · Default: 1

env.MADEIRA_TIMER_FAIRNESS = 1
env.MADEIRA_USD_TIME Text

The same frozen page makes every "N ms have passed since X" test in a guest false for the life of the process: a headless host that sits online and re-checks a condition "5 s after sign-in" never reaches its check, and its own 90 s wall-...

Type: Text

env.MADEIRA_USD_TIME = value
no-local-read On/off

madeira.cfg no-local-read = 1

Type: On/off · Default: 0

no-local-read = 1

Synchronisation

alert-spin-us Number

madeira.cfg alert-spin-us (default 0)

Type: Number · Default: 0

alert-spin-us = 0
eco On/off

Eco scheduling

Runs guest threads at a lower iOS QoS class so the system favours efficiency and saves power; can cost speed. Class chosen by eco-qos.

Type: On/off · Default: 0

eco = 1
eco-qos One of a list

Eco QoS class

The QoS class guest threads run at while eco is on.

Type: One of a list · Choices: , Utility (default), background, Background, initiated, User initiated

eco-qos = 
env.MADEIRA_ALERT_RECHECK_MS Text

somewhere between RtlReleaseSRWLockExclusive and this wait; cause not known. With env MADEIRA_ALERT_RECHECK_MS=N (default 0 = off) a wait that has a readable address wakes every N ms and re-reads the aligned word holding it. Unchanged: k...

Type: Text

env.MADEIRA_ALERT_RECHECK_MS = value
env.MADEIRA_FASTSYNC One of a list

Fastsync (in-process sync, default)

Fastsync is the default engine: with neither this nor inproc-sync set, the app exports auto. Settings > Sync engine > Fastsync removes both keys. Never runs while madsync is on. auto arms the fast wake path on heavy event traffic, 1 from the start, cells only answers polls, 0 is off.

Type: One of a list · Choices: , Default (auto), auto, Auto, 1, On, cells, Poll answers only, 0, Off

env.MADEIRA_FASTSYNC = 
env.MADEIRA_FASTSYNC_CAP_US Text

longest fast park before server_wait, 50..50000 us (2000)

Type: Text

env.MADEIRA_FASTSYNC_CAP_US = value
env.MADEIRA_FASTSYNC_SEM Text

1: semaphores use cells too (off by default)

Type: Text

env.MADEIRA_FASTSYNC_SEM = value
env.MADEIRA_FASTSYNC_SPIN_US Text

adaptive spin ceiling, 0..1000 us (40); 0 = none

Type: Text

env.MADEIRA_FASTSYNC_SPIN_US = value
env.MADEIRA_FS_AUTO_REQS Text

auto: operations in 10 s that arm the wake path (20000, min 1000)

Type: Text

env.MADEIRA_FS_AUTO_REQS = value
env.MADEIRA_FS_POLLPEEK Text

0: no local answer to zero-timeout polls

Type: Text

env.MADEIRA_FS_POLLPEEK = value
env.MADEIRA_MADSYNC_SESSION Text

Madeira Dock: the app sets MADEIRA_MADSYNC_SESSION=0 only for a session that runs a game's one-time installers first (Wine's services.exe never answered its RPC clients under madsync on device). Unset, or any other value: unchanged. Read...

Type: Text

env.MADEIRA_MADSYNC_SESSION = value
inproc-sync On/off

Madsync (in-process sync)

1 selects madsync (Settings > Sync engine > Madsync). Unset: fastsync, the default engine; 0 without env.MADEIRA_FASTSYNC: Wine standard sync.

Type: On/off · Default: 0

inproc-sync = 1
madsync-lock-spin Number

the lock is held for well under a microsecond; a contended pthread_mutex_lock sleeps in the kernel (__psynch_mutexwait, ~20 us measured on average in ph-rdr74, 3.4 k times a second). Spin on trylock first. madeira.cfg madsync-loc...

Type: Number · Default: 256

madsync-lock-spin = 256
madsync-spin-us Number

madeira.cfg madsync-spin-us (default 0 = sleep at once)

Type: Number · Default: 0

madsync-spin-us = 0
yield-depress Number

madeira-duo (6 Nov 2026): no priority depression. Darwin's sched_yield is swtch_pri(0), which drops the thread to priority 0 for up to one quantum (10 ms) whenever anything else is runnable (xnu syscall_subr.c, thread_depress_abstime; Ap...

Type: Number · Default: 1

yield-depress = 1
yield-sleep-us Number

madeira.cfg yield-sleep-us (default 100, 0 = never sleep), yield-streak (256)

Type: Number · Default: 100

yield-sleep-us = 100
yield-streak Number

madeira.cfg yield-sleep-us (default 100, 0 = never sleep), yield-streak (256)

Type: Number · Default: 256

yield-streak = 256

Controllers

env.MADEIRA_CONTROL_PRESETS On/off

Owns madeira-control-presets.json and applies layouts to TouchControlsModel. Main thread only, like the overlay that drives it.

Type: On/off · Default: 1

env.MADEIRA_CONTROL_PRESETS = 1
env.MADEIRA_DINPUT_PAD Text

DirectInput joystick from the host gamepad

Default OFF: see "OPT-IN" at the top of this file. MADEIRA_DINPUT_PAD=1 turns the DirectInput view on for DirectInput-only games.

Type: Text

env.MADEIRA_DINPUT_PAD = value
env.MADEIRA_DINPUT_TRACE Text

Opt-in (MADEIRA_DINPUT_TRACE=1) and limited by a PROCESS-wide call counter: the per-device millisecond limiter never engaged for a title that re-creates its device constantly, and 260,000 trace lines in one session cost more than the inp...

Type: Text

env.MADEIRA_DINPUT_TRACE = value
env.MADEIRA_HIDPAD Text

Set by the app at session start from env.MADEIRA_PAD_MODE (dualsense or generic) for the wineserver and ntdll; not meant to be set by hand.

Type: Text

env.MADEIRA_HIDPAD = value
env.MADEIRA_HIDPAD_AUTO_GENERIC On/off

HID mode: other pads as a generic HID gamepad

1: with env.MADEIRA_PAD_MODE = hid, a pad that is not a PlayStation one becomes a generic HID gamepad and leaves XInput (the old behaviour). Off: it stays on XInput.

Type: On/off · Default: 0

env.MADEIRA_HIDPAD_AUTO_GENERIC = 1
env.MADEIRA_HIDPAD_NAME Text

Set by the app: the product string a generic HID gamepad reports (the physical pad's name).

Type: Text

env.MADEIRA_HIDPAD_NAME = value
env.MADEIRA_HIDPAD_XINPUT On/off

HID mode: keep player 1 on XInput too

1: with the HID controller on, player 1 also stays an XInput pad. Off by default, so a game that reads both APIs does not see the same pad twice.

Type: On/off · Default: 0

env.MADEIRA_HIDPAD_XINPUT = 1
env.MADEIRA_PAD_MODE One of a list

Controller API (player 1)

XInput (default): every controller is an Xbox pad. hid: player 1 becomes a HID game controller, a DualSense (054C:0CE6) when it is a PlayStation pad, and leaves XInput; any other pad stays on XInput. dualsense/generic force the identity. Read at session start; the game's own file wins.

Type: One of a list · Choices: , XInput (default), hid, DirectInput / HID, dualsense, HID, always a DualSense, generic, HID, always a generic gamepad

env.MADEIRA_PAD_MODE = 
env.MADEIRA_PAD_OUTPUT One of a list

Rumble, adaptive triggers and lightbar to the pad

On (default): XInput rumble plays on the controller (CoreHaptics), and in DualSense HID mode the game's output reports drive rumble, adaptive triggers (closest GameController mode), lightbar and player LEDs. hid: only the DualSense's; xinput: only XInput rumble; 0: none. Read at session start; the game's own file wins.

Type: One of a list · Choices: , On (default), hid, DualSense output only, xinput, XInput rumble only, 0, Off

env.MADEIRA_PAD_OUTPUT = 
env.MADEIRA_WGI_HOST_PADS On/off

Controllers in Windows.Gaming.Input

Default off. 1: each connected XInput controller (a paired pad or the touch controller) is also a Windows.Gaming.Input gamepad, an Xbox pad to the game, with rumble. For games that read their controller only that way (Horizon Zero Dawn); a game that also reads XInput could list it twice. Read when the game first asks for a gamepad.

Type: On/off · Default: 0

env.MADEIRA_WGI_HOST_PADS = 1
env.MADEIRA_XINPUT_BATTERY On/off

Controller battery level to XInput

On (default): XInputGetBatteryInformation reports each pad's GameController battery (wired while charging, else a level) and XInputGetCapabilities flags a battery-powered pad as wireless. 0: an unknown battery, as before.

Type: On/off · Default: 1

env.MADEIRA_XINPUT_BATTERY = 1
env.MADEIRA_XINPUT_ENABLE_FOREGROUND On/off

Ignore a stale XInput disable while the game is in front

On (default): when a game has switched XInput off (XInputEnable(FALSE), usually on losing focus) but its window is in front, it still reads the pad; activation messages at startup can leave it off for good. 0: the pad reads at rest while disabled, as before. Read by win32u, so 32- and 64-bit games alike.

Type: On/off · Default: 1

env.MADEIRA_XINPUT_ENABLE_FOREGROUND = 1
env.MADEIRA_XINPUT_PROFILE_CHECK On/off

Re-read a controller's input profile

on (default): every 2 s the app checks each connected controller's extended-gamepad profile and, when GameController has replaced it (a remap or a mode change after the controller joined), reads the live one; the first 8 times the sticks leave rest the raw values are logged ([xinput] ). 0: a slot keeps the profile its controller had when it joined, as before.

Type: On/off · Default: 1

env.MADEIRA_XINPUT_PROFILE_CHECK = 1
env.MADEIRA_XINPUT_SLOT0_RECONNECT On/off

Reconnected controller back to player 1

On (default): when player 1's controller reconnects and GameController reports it as a new controller before the old one leaves, it is moved from the slot it landed in back to slot 0. 0: it stays where it landed, as before.

Type: On/off · Default: 1

env.MADEIRA_XINPUT_SLOT0_RECONNECT = 1

Vulkan routes

d3d11 One of a list

Direct3D 10/11 runtime (x64)

Unset: DXMT, Direct3D 10/11 on Metal. "dxvk": this session's d3d11.dll, d3d10core.dll and dxgi.dll are DXVK's (Direct3D 10/11 and DXGI on Vulkan, the bundle's vulkan/ folder), replacing DXMT for Direct3D 10/11 and DXGI; Vulkan is on (see vulkan). DXVK's DXGI only presents for Vulkan devices, so Direct3D 12 pairs with vkd3d-proton: with d3d12 unset this implies d3d12 = vkd3d. x64 programs only; read at session start; also from a game's own lines. Experimental, not device-tested.

Type: One of a list · Choices: , DXMT (default), dxvk, DXVK on Vulkan

d3d11 = 
d3d12 One of a list

Direct3D 12 runtime (x64)

Unset: madeira-d3d12, Direct3D 12 on Metal. "vkd3d": this session's d3d12.dll and d3d12core.dll are vkd3d-proton's (Direct3D 12 on Vulkan, the bundle's vulkan/ folder) and Vulkan is on (see vulkan). x64 programs only; read at session start; also from a game's own lines. Not device-tested. "1" (developer) runs madeira-d3d12's shader converter canary at app start.

Type: One of a list · Choices: , madeira-d3d12 (default), vkd3d, vkd3d-proton on Vulkan

d3d12 = 
env.DXVK_CONFIG Text

DXVK options

dxvk.conf options inline, separated by ';' (e.g. dxgi.maxFrameRate=60;d3d11.cachedDynamicResources=a); applied after the config file; with d3d11 = dxvk.

Type: Text

env.DXVK_CONFIG = value
env.DXVK_CONFIG_FILE Text

DXVK config file

A dxvk.conf to read instead of the one in the program's working folder (a Windows path, e.g. C:\users\madeira\dxvk.conf); with d3d11 = dxvk. See DXVK's dxvk.conf for the options.

Type: Text

env.DXVK_CONFIG_FILE = value
env.DXVK_LOG_LEVEL Text

DXVK log level

DXVK's log (none, error, warn, info, debug, trace), written to the session log through Wine's debug output. d3d11 = dxvk sets info unless this is set.

Type: Text

env.DXVK_LOG_LEVEL = value
env.MADEIRA_DXGI_VK_SWAPCHAIN On/off

DXGI swapchains for vkd3d-proton

On (default): DXMT's DXGI presents for a Direct3D 12 device on Vulkan (d3d12 = vkd3d) by wrapping vkd3d-proton's swapchain (IDXGIVkSwapChainFactory); windowed only, a fullscreen request keeps the window. 0: CreateSwapChain fails with "Unsupported device type" for those devices, as before.

Type: On/off · Default: 1

env.MADEIRA_DXGI_VK_SWAPCHAIN = 1
env.VKD3D_CONFIG Text

vkd3d-proton options

Comma-separated vkd3d-proton flags (e.g. no_upload_hvv, force_static_cbv, skip_driver_workarounds); with d3d12 = vkd3d. See vkd3d-proton's README.

Type: Text

env.VKD3D_CONFIG = value
env.VKD3D_DEBUG Text

vkd3d-proton log level

vkd3d-proton's log: none, err, warn, fixme (default), info, trace. Passed to the Windows environment like any env line; only with d3d12 = vkd3d.

Type: Text

env.VKD3D_DEBUG = value
env.VKD3D_SHADER_DEBUG Text

vkd3d-proton shader log level

The shader translators' log level (none, err, warn, fixme, info, trace); with d3d12 = vkd3d.

Type: Text

env.VKD3D_SHADER_DEBUG = value
vulkan One of a list

Vulkan library (x64)

The Vulkan driver Wine's winevulkan loads: moltenvk = gl/libMoltenVK.dylib (the one Zink uses), kosmickrisp = gl/libvulkan_kosmickrisp.dylib, or a .dylib path (absolute or bundle-relative). Setting it turns Vulkan on for x64 programs (vulkan-1.dll and winevulkan.dll in the prefix); unset, Vulkan is off unless d3d12 = vkd3d or d3d11 = dxvk. Read at session start; also from a game's own lines.

Type: One of a list · Choices: , Off, MoltenVK with d3d12 = vkd3d or d3d11 = dxvk, moltenvk, MoltenVK, kosmickrisp, KosmicKrisp, off, Off

vulkan = 

Audio

env.MADEIRA_AUDIO_DOWNMIX On/off

Mix surround sound down to stereo

On by default: a game that plays 5.1 or 7.1 sound has every channel folded into the two speakers, so voices (in the centre channel), bass and the rear channels are heard. Off keeps only the front left and right channels, as Madeira did before, which loses most dialogue in a surround game. Applies at the next game start.

Type: On/off · Default: 1

env.MADEIRA_AUDIO_DOWNMIX = 1
env.MADEIRA_AUDIO_GAIN Number

Game volume at the output (%)

Percent of the game's level, 10-200; unset or 100 leaves it unchanged. Read once, at the first audio endpoint. Set it in the game's own file.

Type: Number · Default: 100

env.MADEIRA_AUDIO_GAIN = 100
env.MADEIRA_AUDIO_IO_US Text

The shared-mode engine period, in 100 ns units. A client that keeps one period queued (IAudioClient3) must cover a whole RemoteIO slice, or every render callback empties its queue and plays silence for the rest: at least two slices of th...

Type: Text

env.MADEIRA_AUDIO_IO_US = value
env.MADEIRA_AUDIO_LEAD_MS One of a list

Sound buffer

How much sound Madeira keeps queued ahead of the speaker (10-500 ms, default 60). If a game's sound crackles or sounds scratchy, a larger buffer usually clears it, at the cost of sound lagging slightly behind the picture: Black Ops II's Zombies crackled at 60 ms and was clean at 150. A game's own config can set it for that game alone. Applies at the next game start.

Type: One of a list · Choices: , 60 ms (default), 100, 100 ms, 150, 150 ms, 200, 200 ms, 300, 300 ms

env.MADEIRA_AUDIO_LEAD_MS = 
env.MADEIRA_AUDIO_MIX On/off

Play alongside other apps' audio

Default on: a game's sound mixes with other apps', so a Discord voice call or music keeps playing while Madeira runs. 0: Madeira's audio stops the others, as before. Read when a session starts.

Type: On/off · Default: 1

env.MADEIRA_AUDIO_MIX = 1
env.MADEIRA_AUDIO_PERIOD_MS Text

The shared-mode engine period, in 100 ns units. A client that keeps one period queued (IAudioClient3) must cover a whole RemoteIO slice, or every render callback empties its queue and plays silence for the rest: at least two slices of th...

Type: Text

env.MADEIRA_AUDIO_PERIOD_MS = value
env.MADEIRA_AUDIO_RESUME On/off

Bring game audio back after an interruption

Default off: after a call, Siri, an alarm or a suspension the sound stays off until the game restarts. 1: the audio session is activated again and the output restarted; while iOS holds it stopped the game's audio clock keeps running. Logged as [audio] interruption began / ended. Read when the session starts.

Type: On/off · Default: 0

env.MADEIRA_AUDIO_RESUME = 1
env.MADEIRA_AUDIO_SPATIAL Text

0: no spatial audio (a game falls back to a plain stream); unset or 1: Wine's spatial audio, as before

Type: Text

env.MADEIRA_AUDIO_SPATIAL = value

Wine libraries

env.MADEIRA_DNS_TIMEOUT_MS Text

No description written yet.

Type: Text

env.MADEIRA_DNS_TIMEOUT_MS = value
env.MADEIRA_MFC On/off

Microsoft MFC (mfc140.dll, mfc140u.dll)

On by default. MFC comes from the same Microsoft VC++ package as the C++ runtime and is linked into the game's system32; games that import it (Horizon Zero Dawn) stop at once without it. Wine has no MFC of its own. 0 leaves it out. Read at session start.

Type: On/off · Default: 1

env.MADEIRA_MFC = 1
env.MADEIRA_MONO_DEFAULTS Text

Wine Mono, 32- and 64-bit: mscoree sets MONO_THREADS_SUSPEND=coop and adds keep-delegates to MONO_DEBUG before Mono loads, and puts the previous values back once Mono has read them ; values already set win. 0 sets nothing.

Type: Text

env.MADEIRA_MONO_DEFAULTS = value
env.MADEIRA_NSI_DEVICE_CACHE Text

On by default: without \\.\Nsi, the failed open is remembered instead of being retried on every call. 0 retries every time.

Type: Text

env.MADEIRA_NSI_DEVICE_CACHE = value
env.MADEIRA_NSI_NOTIFY_PENDING Text

On by default: without \\.\Nsi, an address-change request stays pending (the addresses do not change) instead of failing at once. 0 fails it as before.

Type: Text

env.MADEIRA_NSI_NOTIFY_PENDING = value
env.MADEIRA_SCM_ON_DEMAND On/off

Start the service manager when a program needs it

on (default): when a 64-bit program opens the service manager and services.exe is not running (the session did not start Windows services first), sechost starts it once per process, waits up to 20 s for its pipe and asks again. Before, the call failed: a game from another store whose first start runs a launcher installer could not register the launcher's service and the installer stopped (testers' logs, 2026-10-28: a publisher's launcher installer run by an Epic copy's first start). 0: as before.

Type: On/off · Default: 1

env.MADEIRA_SCM_ON_DEMAND = 1
env.MADEIRA_SETUPAPI_MEDIA_FIX Text

Madeira ask for the media again only when the answer named a new place to look. An unattended install's callback (the default one included) answers "same place" forever, and the loop never ended; report a copy error instead. Idea...

Type: Text

env.MADEIRA_SETUPAPI_MEDIA_FIX = value
env.MADEIRA_ZERO_MITIGATION_POLICY Text

uninitialised PROCESS_MITIGATION_CONTROL_FLOW_GUARD_POLICY, and when EnableControlFlowGuard (bit 0) happens to be set it looks up SetProcessValidCallTargets in api-ms-win-core-memory-l1-1-3.dll, which this Wine does not export, and calls...

Type: Text

env.MADEIRA_ZERO_MITIGATION_POLICY = value

Debugging / logs

env.MADEIRA_BAND_CENSUS On/off

Log the 64 GB address band by piece

Default off. 1: about once a minute and when a large reserve fails, [band] lines say what each piece of [0x7000000000, 0x8000000000) uses (Social Club's pools and metadata, the furniture, the V8 and Oilpan cages, the FEX arena), the largest free gap, and whether Red Dead Redemption 2's 8960 MB reserve fits; 64 censuses at most. Logging only, changes no placement; read at session start.

Type: On/off · Default: 0

env.MADEIRA_BAND_CENSUS = 1
env.MADEIRA_EC_HOOK_TRACE On/off

Log code patches the emulated copy misses

Default off, logging only. 1 compares executable PE sections and their pool copies before sync, including x64 entry thunks. Separate budgets preserve later graphics-jump records after native startup rewrites. A difference alone does not prove an inline hook.

Type: On/off · Default: 0

env.MADEIRA_EC_HOOK_TRACE = 1
env.MADEIRA_IMAGE_PATCH_TRACE On/off

DLL code patch trace

1 logs up to 64 successful 1–16 byte executable-image protection requests and their PE/pool bytes. Read-only, owner-aware diagnostics; does not alter hooks or code.

Type: On/off · Default: 0

env.MADEIRA_IMAGE_PATCH_TRACE = 1
env.MADEIRA_LEAN_DIAG On/off

Lean diagnostics (no thread-suspending samplers)

1: the samplers that suspend threads stop ([thread-sample] bursts every 20 s, the guest RIP profile behind [rip-profile] and [cpu-split], [wprof]); the warmer's address-space walks ([phys-map], slot and window inventory) run every ~10 min instead of every minute, its zone check and allocation probe every minute instead of every 2 s; mprotect_exec's per-call ERR line is kept for the first 200 calls, then every 1000th. [xp], [xp-t], [xp-api] and [sync-census] keep their rates. Off (default): every diagnostic as before. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_LEAN_DIAG = 1
env.MADEIRA_POWER_PROBE On/off

Log GPU and device power every 5 s

1: every 5 s a [power] line next to [xp]'s CPU energy: the GPU energy and time the driver charged to the app's coalition, the SoC's Energy Model counters (IOReport) and the battery's voltage and current (the whole device while unplugged), each source named unavailable once when the system gives nothing; and [power-t], the threads that used the most energy. Off (default): nothing is read. Needs the [xp] sampler. Read at session start.

Type: On/off · Default: 0

env.MADEIRA_POWER_PROBE = 1

Media

env.MADEIRA_WG_PARSER Text

No description written yet.

Type: Text

env.MADEIRA_WG_PARSER = value
env.MADEIRA_WG_VIDEO Text

Media: MP4 video (32-bit programs)

0 limits the media parser to MP3/WAV; by default MP4 with H.264/HEVC video decodes through VideoToolbox.

Type: Text

env.MADEIRA_WG_VIDEO = value
env.MADEIRA_WG_VIDEO_FORMAT Text

No description written yet.

Type: Text

env.MADEIRA_WG_VIDEO_FORMAT = value
env.MADEIRA_WMA_DUMP Text

No description written yet.

Type: Text

env.MADEIRA_WMA_DUMP = value
env.MADEIRA_WMA_SEARCH Text

MADEIRA_WMA_SEARCH=0 pins the decoder to the rate and flags this file worked out from the media type alone, which is what shipped before the ladder. A packet it cannot decode is then concealed with silence of that packet's length...

Type: Text

env.MADEIRA_WMA_SEARCH = value

Graphics

env.MADEIRA_GL_QUERY_BUFFER_OFFSETS On/off

32-bit GL query results as buffer offsets

On (default): a 32-bit program's glGetQueryObject*v result pointer is an offset into the bound GL_QUERY_BUFFER (wined3d reads occlusion results that way; converting it as a pointer left the game spinning at 1 fps, ). 0: the old pointer conversion.

Type: On/off · Default: 1

env.MADEIRA_GL_QUERY_BUFFER_OFFSETS = 1
gl-vulkan One of a list

Vulkan driver for OpenGL (Zink)

The Vulkan driver Zink runs desktop OpenGL (and d3d9 = wined3d) on: MoltenVK (default) or KosmicKrisp (gl/libvulkan_kosmickrisp.dylib); any other value is a .dylib name in the gl folder or an absolute path. env.MADEIRA_GL_VULKAN is the fallback. Read when a program first creates an OpenGL context; the log says " zink Vulkan library: ...".

Type: One of a list · Choices: , MoltenVK (default), moltenvk, MoltenVK, kosmickrisp, KosmicKrisp

gl-vulkan =