From fc9dc2d9734603babecaadacc81bd13081054336 Mon Sep 17 00:00:00 2001
From: Roxas2712 <Roxas2712@users.noreply.github.com>
Date: Tue, 27 Oct 2026 10:48:49 +0100
Subject: [PATCH 1/2] Render verified native FRLG level-up streaks with
 queue-owned timing

---
 LICENSE-ROXAS2712.md                       | 88 ++++++++++++++++++++++
 src/battle/BattleState.lua                 | 15 ++++
 src/battle/Gen3Battle.lua                  |  5 ++
 src/battle/Gen3LevelUpStreaks.lua          | 78 +++++++++++++++++++
 src/core/game3/battle/level_up_streaks.lua | 34 +++++++++
 src/import/Gen3LevelUpArt.lua              | 49 ++++++++++++
 src/import/RomExtractorGen3.lua            | 18 +++++
 src/import/RomImporter.lua                 |  4 +
 src/render/NativeGbaAlpha.lua              | 68 +++++++++++++++++
 tests/engine/native_level_up_facade.lua    | 41 ++++++++++
 tests/engine/native_level_up_streaks.lua   | 66 ++++++++++++++++
 tools/native-level-up-blend/conf.lua       |  6 ++
 tools/native-level-up-blend/main.lua       | 75 ++++++++++++++++++
 tools/native-level-up/conf.lua             |  6 ++
 tools/native-level-up/main.lua             | 35 +++++++++
 15 files changed, 588 insertions(+)
 create mode 100644 LICENSE-ROXAS2712.md
 create mode 100644 src/battle/Gen3LevelUpStreaks.lua
 create mode 100644 src/core/game3/battle/level_up_streaks.lua
 create mode 100644 src/import/Gen3LevelUpArt.lua
 create mode 100644 src/render/NativeGbaAlpha.lua
 create mode 100644 tests/engine/native_level_up_facade.lua
 create mode 100644 tests/engine/native_level_up_streaks.lua
 create mode 100644 tools/native-level-up-blend/conf.lua
 create mode 100644 tools/native-level-up-blend/main.lua
 create mode 100644 tools/native-level-up/conf.lua
 create mode 100644 tools/native-level-up/main.lua

diff --git a/LICENSE-ROXAS2712.md b/LICENSE-ROXAS2712.md
new file mode 100644
index 000000000..fbcffd47c
--- /dev/null
+++ b/LICENSE-ROXAS2712.md
@@ -0,0 +1,88 @@
+# Roxas2712 — Fork Contributions
+
+Version 1.0 · Effective 25 October 2026
+
+Copyright © 2026 Roxas2712, to the extent of rights held.
+All rights reserved except as expressly granted below or already granted.
+
+## 1. Scope and ownership
+
+This notice applies only to original contributions made by Roxas2712
+(GitHub: Roxas2712) to `Roxas2712/Gen2Recomped`, including original additions
+within modified files, insofar as he owns the relevant rights. Git history,
+pull-request diffs and source provenance identify contributions; a commit
+author or a whole-file change alone does not establish ownership of every
+part of that file.
+
+It does not claim ownership of Cedric's work, Gen1Recomp / BOIS CLUB GAMES
+work, other contributors' work, third-party dependencies, or ROM-derived
+content. Their applicable licences and notices remain in force. It does not
+grant permission to distribute the complete combined fork where another
+rights holder's permission is required.
+
+## 2. General permission and reserved rights
+
+For contributions covered by this notice and not already licensed more
+broadly, you may read and study the published source and make private,
+non-commercial modifications and builds for your own use. This grants no
+general permission to redistribute, sublicense, sell, or offer those
+contributions as a hosted service. Other uses require Roxas2712's
+written permission, except for the specific permission below and rights
+available independently under applicable law.
+
+Keep the relevant copyright, licence and attribution notices. Do not
+represent Roxas2712's contributions as exclusively authored by someone
+else. Public source availability alone does not put them in the public
+domain or grant an open-source licence.
+
+## 3. Specific permission for Cedric / UNDERdecoded
+
+Roxas2712 expressly grants Cedric (Ced; GitHub: UNDERdecoded /
+UNDERdecodedHD) a non-exclusive, worldwide, perpetual, royalty-free
+permission to use, reproduce, integrate, modify and distribute the covered
+contributions that Roxas2712 submits or expressly offers through pull
+requests to `UNDERdecoded/Gen2Recomped`, for Cedric's Gen2Recomped /
+RetroRecompiled project. This includes its renamed continuation maintained
+by Cedric, its official builds, and its commercial operation.
+
+Cedric may license the incorporated contributions to recipients as part of
+that project, subject to preserving this permission's applicable credit and
+notice requirements. This permission is not a copyright assignment, is not
+exclusive, and does not cover unpublished work, separate repositories,
+ModCompass service operation, credentials, or content not offered in those
+pull requests. Roxas2712 retains his own rights to his contributions.
+
+For uses relying on this permission:
+
+- retain the relevant source copyright and licence notices;
+- give visible credit in the project's README or equivalent public project
+  page, and in the application's existing About / Credits view, if present;
+- use at least the following credit, or a substantially equivalent one:
+
+  > Contributions by Roxas2712 —
+  > https://github.com/Roxas2712
+
+A maintained consolidated contributor credit is sufficient; a separate
+credit on every screen or for every change is not required. Adapted
+contributions must not be attributed exclusively to another author. Other
+contributors' credits must also remain intact.
+
+## 4. Earlier licences and permissions remain effective
+
+This notice does not revoke, narrow, or retrospectively add conditions to
+any permission already validly granted, including MIT / GPL grants,
+separate agreements, or permissions arising from previously submitted
+pull requests. Where an earlier grant permits a use independently of this
+notice, its existing terms govern that use. For such earlier uses, the
+visible credit above is requested to the extent it is not already required.
+
+For subsequent contributions, this is the default statement of Roxas2712's own reserved rights and the specific PR permission, subject to any
+applicable existing licence obligations or separately agreed terms. It
+does not change another rights holder's licence or guarantee compatibility
+of a particular combination of code.
+
+## 5. No warranty
+
+To the extent permitted by applicable law, these contributions are provided
+as is, without warranty. No support obligation, endorsement, or rights to
+third-party code, game assets, names, or trademarks are granted.
diff --git a/src/battle/BattleState.lua b/src/battle/BattleState.lua
index 8f8e1409c..8795b119e 100644
--- a/src/battle/BattleState.lua
+++ b/src/battle/BattleState.lua
@@ -2605,6 +2605,7 @@ function BattleState:beginMsgLine()
 end
 
 function BattleState:updateQueue()
+  if self._levelUpStreaks and require('src.battle.Gen3LevelUpStreaks').update(self)then return true end
   if self.waitingUI then
     if self.game.stack:top() ~= self then return true end
     self.waitingUI = nil
@@ -2728,6 +2729,10 @@ function BattleState:updateQueue()
   end
   if not self.current then
     local item = table.remove(self.queue, 1)
+    while item and item.gbaLevelUpStreaks do
+      if require('src.battle.Gen3LevelUpStreaks').start(self,item)then return true end
+      item=table.remove(self.queue,1)
+    end
     if not item then return false end
     if item.fn then
       self.nextInsert = 0 -- sayNext inserts right after this item
@@ -3895,6 +3900,7 @@ end
 -- any pop (finish, script teardown) must silence the alarm loop
 -- (end_of_battle.asm clears wLowHealthAlarm when a battle ends)
 function BattleState:exit()
+  require('src.battle.Gen3LevelUpStreaks').release(self)
   -- Teachy TV temporarily replaces the player's party exactly like
   -- SavePlayerParty/LoadPlayerParty in teachy_tv.c.  finish() normally
   -- restores it before the pop, but exit is the safety net for a forced state
@@ -8954,6 +8960,15 @@ function BattleState:awardExp(fallen)
         require("src.pokemon.Evolution").changeHappiness(mon, "LEVELUP")
       end
       self:sayNext(Strings("%s grew\nto level %d!", name, lv))
+      if GameVersion.isGen3() and self.data.constants.gen3LevelUpStreaks then
+        for position=0,3 do
+          local actor=self:battlerAt(position)
+          if actor and actor.mon==mon then
+            require('src.battle.Gen3LevelUpStreaks').queue(self,actor)
+            break
+          end
+        end
+      end
       self:uiNext(function()
         require("src.core.Sound").play(game.data, "Level_Up")
         return StatBox.new(game, mon)
diff --git a/src/battle/Gen3Battle.lua b/src/battle/Gen3Battle.lua
index dcaa62f71..fa6ddd971 100644
--- a/src/battle/Gen3Battle.lua
+++ b/src/battle/Gen3Battle.lua
@@ -3104,6 +3104,11 @@ function Gen3Battle.draw(battle)
   -- over them.  The methods dispatch back here (BattleState:drawHUDs and
   -- friends), so the implementation is still this file's; what changed is
   -- that there is now a door in front of it.
+  shaken(function()
+    local layer=package.loaded['src.core.game3.battle.level_up_streaks']
+    local draw=function()return require('src.battle.Gen3LevelUpStreaks').draw(battle)end
+    if layer then layer._nativeDraw(battle,draw)else draw()end
+  end)
   shaken(function() battle:drawHUDs(slide) end)
   -- the ball rides with the pics rather than with the windows: it is thrown
   -- across the field, and a screen shake moves the field
diff --git a/src/battle/Gen3LevelUpStreaks.lua b/src/battle/Gen3LevelUpStreaks.lua
new file mode 100644
index 000000000..68f940b97
--- /dev/null
+++ b/src/battle/Gen3LevelUpStreaks.lua
@@ -0,0 +1,78 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+-- Pure samples of the native 18-sprite sequence, driven by BattleState.frame.
+-- No RNG, timer, GPU object, battle or save is retained here.
+-- Interface/timing facts: pinned pret/pokefirered pokemon_special_anim_scene.c
+-- and random.h (ce6406d8). Integer low bits avoid floating LCG overflow.
+local M={}
+local finish=0
+for index=1,18 do
+ local speed=(45*index+51)%64+32
+ finish=math.max(finish,2*(index-1)+math.floor(1024/speed)+1)
+end
+function M.busy(frame)return frame<finish end
+function M.queue(battle,user)
+ if not require('src.core.GameVersion').isGen3()or not battle.data.constants.gen3LevelUpStreaks then return false end
+ battle.nextInsert=(battle.nextInsert or 0)+1
+ table.insert(battle.queue,battle.nextInsert,{gbaLevelUpStreaks=true,position=user.position,
+  isPlayer=user.isPlayer})
+ return true
+end
+function M.start(battle,row)
+ if not require('src.core.GameVersion').isGen3()then return false end
+ local user=row.position~=nil and battle:battlerAt(row.position)
+  or(row.isPlayer and battle.player or battle.enemy)
+ local hidden=battle.picFx and user and battle.picFx[user]and battle.picFx[user].hidden
+ if not(user and user.mon and user.mon.hp>0 and not user.fainted and not hidden
+  and battle.data.constants.gen3LevelUpStreaks)then return false end
+ battle._levelUpStreaks={user=user,startFrame=battle.frame}
+ local options=battle.game and battle.game.save and battle.game.save.options or{}
+ require('src.core.Sound').playSe(battle.data,'SE_RS_SHOP',{mono=options.stereo==false})
+ return true
+end
+function M.update(battle)
+ local state=battle._levelUpStreaks
+ if not state then return false end
+ if M.busy(battle.frame-state.startFrame)then return true end
+ battle._levelUpStreaks=nil
+ return false
+end
+function M.sample(frame,visit)
+ assert(type(frame)=='number'and frame==frame and frame>=0 and frame%1==0,'invalid native streak frame')
+ assert(type(visit)=='function','native streak visitor must be callable')
+ local alive=0
+ -- Reverse OAM order: the first-created sprite remains in front of siblings.
+ for index=18,1,-1 do
+  local age=frame-2*(index-1)
+  if age>=0 then
+   local speed=(45*index+51)%64+32
+   local y=math.floor(-speed*age/16)
+   if y>=-64 then
+    alive=alive+1;visit((index*219)%64-32,32+y,index,speed)
+   end
+  end
+ end
+ return alive>0 or frame<34,alive
+end
+function M.release(battle)
+ if battle._levelUpBlend then battle._levelUpBlend:release();battle._levelUpBlend=nil end
+ battle._levelUpStreaks=nil
+end
+function M.draw(battle)
+ local state=battle._levelUpStreaks
+ if not state then return false end
+ local record=battle.data.constants.gen3LevelUpStreaks
+ if not record then return false,'native vertical-streak resource unavailable'end
+ local x,y=require('src.battle.Gen3Battle').battlerCentre(battle,state.user)
+ if not x then return false,'native vertical-streak battler has no drawn sprite'end
+ local image=require('src.render.Assets').image(record.image)
+ local blend=battle._levelUpBlend
+ if not blend then blend=require('src.render.NativeGbaAlpha').new();battle._levelUpBlend=blend end
+ local ok,why=blend:paint(12,6,function()
+  M.sample(battle.frame-state.startFrame,function(dx,dy)
+   love.graphics.draw(image,x+dx,y+dy,0,1,1,4,8)
+  end)
+ end)
+ if not ok then error(why,0)end
+ return true
+end
+return M
diff --git a/src/core/game3/battle/level_up_streaks.lua b/src/core/game3/battle/level_up_streaks.lua
new file mode 100644
index 000000000..416797f3f
--- /dev/null
+++ b/src/core/game3/battle/level_up_streaks.lua
@@ -0,0 +1,34 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+-- Borrow the native queue-owned effect. The source facade owns no timer,
+-- artwork, battle state or renderer resources.
+local Battle=require('src.core.game3.battle')
+local Streaks=require('src.battle.Gen3LevelUpStreaks')
+local Scope=require('src.render.GraphicsScope')
+local Boundary=require('src.compat.gen1.ScriptBoundary')
+local Call=require('src.compat.gen1.SourceCall')
+local M={}
+local unpack=table.unpack or unpack
+local function pack(...)return{n=select('#',...),...}end
+local function draw(state)
+ if Boundary.active('battle.levelup.draw')then return Boundary.invoke('battle.levelup.draw')end
+ local screen=Battle._screen(state)
+ if not screen then return false,'no admitted native battle'end
+ return Streaks.draw(screen)
+end
+M.draw=draw
+function M._nativeDraw(screen,body)
+ if M.draw==draw or Battle._screen()~=screen then return body(screen)end
+ if Boundary.active('battle.levelup.draw')then return Boundary.invoke('battle.levelup.draw')end
+ local stack=screen.game.stack;local top=stack:top()
+ local result=pack(Scope.call(function()
+  return Boundary.dispatch('battle.levelup.draw',function()
+   if Battle._screen()~=screen or screen.game.stack~=stack or stack:top()~=top then
+    return false,'native level-up presentation admission changed'
+   end
+   return body(screen)
+  end,function()return Call.call(M,'draw',Battle.getState())end)
+ end))
+ if not result[1]then error(result[2],0)end
+ return unpack(result,2,result.n)
+end
+return M
diff --git a/src/import/Gen3LevelUpArt.lua b/src/import/Gen3LevelUpArt.lua
new file mode 100644
index 000000000..818c7cf80
--- /dev/null
+++ b/src/import/Gen3LevelUpArt.lua
@@ -0,0 +1,49 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+-- FRLG's additional vertical streaks use their own 8x16 cartridge sprite.
+-- Offsets were found by matching every decoded pixel/palette word against
+-- pret/pokefirered ce6406d8's level_up.png, then checked on both exact ROMs.
+-- Publish hashes and addresses only; artwork remains in the user's cartridge.
+local Version=require('src.core.GameVersion')
+local M={REVISION=1}
+local profiles={firered={gfx=4561032,palette=4561000},leafgreen={gfx=4559528,palette=4559496}}
+local gfxDigest='0dbfbcf3f4a3fef33ba7449f89c2e510f780dfc063c4dd631c1715d3848152b5'
+local palDigest='fbd58ce9122f0aa5058167d5e185820f19ba95d86f5ed52629d19bf2b0937f9a'
+function M.supports(edition)return profiles[edition]~=nil end
+local function digest(bytes)
+ return love.data.encode('string','hex',love.data.hash('sha256',bytes))
+end
+function M.read(x)
+ local edition=type(x.version)=='table'and x.version.id or x.version
+ local profile=profiles[edition]
+ if not profile then return nil,'no native vertical-streak profile for this edition'end
+ local info=Version.info(edition)
+ if not(x.manifest and x.manifest.romSha1==info.sha1)
+  or require('src.import.RomVerification').sha1(x.rom.data)~=info.sha1 then
+  return nil,'native vertical-streak cartridge fingerprint mismatch'
+ end
+ local ok,tiles=pcall(x.rom.lz77,x.rom,profile.gfx)
+ if not ok or type(tiles)~='table'or #tiles~=64 then return nil,'invalid native vertical-streak tile size'end
+ local packed={};for i=1,#tiles do packed[i]=string.char(tiles[i])end
+ if digest(table.concat(packed))~=gfxDigest then return nil,'native vertical-streak tile fingerprint mismatch'end
+ local palette,raw={},{}
+ for index=0,15 do
+  local color=x.rom:u16(profile.palette+index*2)
+  if color>=32768 then return nil,'invalid native vertical-streak palette'end
+  palette[index]=color;raw[#raw+1]=string.char(color%256,math.floor(color/256))
+ end
+ if digest(table.concat(raw))~=palDigest then return nil,'native vertical-streak palette fingerprint mismatch'end
+ return {tiles=tiles,palette=palette,width=8,height=16,edition=edition,
+  romSha1=info.sha1,gfxOffset=profile.gfx,paletteOffset=profile.palette}
+end
+function M.image(record)
+ local image=require('src.import.ImageWriter').blank(8,16)
+ for y=0,15 do for x=0,7 do
+  local byte=record.tiles[y*4+math.floor(x/2)+1]
+  local index=math.floor(byte/(x%2==0 and 1 or 16))%16
+  local color=record.palette[index]
+  image:setPixel(x,y,(color%32)/31,(math.floor(color/32)%32)/31,
+   (math.floor(color/1024)%32)/31,index==0 and 0 or 1)
+ end end
+ return image
+end
+return M
diff --git a/src/import/RomExtractorGen3.lua b/src/import/RomExtractorGen3.lua
index c2ce0b55e..b621537ca 100644
--- a/src/import/RomExtractorGen3.lua
+++ b/src/import/RomExtractorGen3.lua
@@ -54302,6 +54302,23 @@ RomExtractorGen3.BATTLE_TEXTBOX = {
   CURSOR_AT = { { 128, 120 }, { 184, 120 }, { 128, 136 }, { 184, 136 } },
 }
 
+function RomExtractorGen3:extractLevelUpStreaks()
+  local Art=require('src.import.Gen3LevelUpArt')
+  local edition=type(self.version)=='table'and self.version.id or self.version
+  if not Art.supports(edition)then return end
+  self:beginStage('Gen3 level-up streaks')
+  local record,why=Art.read(self)
+  assert(record,why)
+  local image=Art.image(record)
+  self:saveImage(image,'battle/level_up_streak.png')
+  image:release()
+  self._constants=self._constants or{}
+  self._constants.gen3LevelUpStreaks={image='assets/generated/battle/level_up_streak.png',
+    width=record.width,height=record.height,romSha1=record.romSha1,
+    gfxOffset=record.gfxOffset,paletteOffset=record.paletteOffset}
+  self:write('constants',self._constants)
+end
+
 function RomExtractorGen3:extractBattleTextbox()
   self:beginStage("Gen3 battle textbox")
   local T = RomExtractorGen3.BATTLE_TEXTBOX
@@ -58871,6 +58888,7 @@ RomExtractorGen3.ASSET_STAGES = {
   "extractItemIcons",
   "extractPokenav",
   "extractBattleTextbox",
+  "extractLevelUpStreaks",
   "extractPokedexScreen",
   "extractBallAnims",
   "extractSummaryWindows",
diff --git a/src/import/RomImporter.lua b/src/import/RomImporter.lua
index bbd959cfd..95a494247 100644
--- a/src/import/RomImporter.lua
+++ b/src/import/RomImporter.lua
@@ -1323,6 +1323,10 @@ local function markerFor(version)
   if version == "red" or version == "blue" or version == "yellow" then
     revision = "gen1-trade-art-v1:"
   end
+  local levelArt=require('src.import.Gen3LevelUpArt')
+  if GameVersion.generation(version)==3 and levelArt.supports(version)then
+    revision=revision..'gba-levelup-streaks-v'..levelArt.REVISION..':'
+  end
   return CACHE_FORMAT .. revision .. GameVersion.info(version).sha1
 end
 
diff --git a/src/render/NativeGbaAlpha.lua b/src/render/NativeGbaAlpha.lua
new file mode 100644
index 000000000..d7d2849d7
--- /dev/null
+++ b/src/render/NativeGbaAlpha.lua
@@ -0,0 +1,68 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+-- OAM alpha against a snapshot of the underlying native surface. Sibling
+-- sprites do not become each other's second target. Each caller owns/releases
+-- this small cache; no borrowed Canvas, Image or Shader is released here.
+local Scope=require('src.render.GraphicsScope')
+local unpack=table.unpack or unpack
+local A={};A.__index=A
+A.SOURCE=[[
+extern Image nativeGbaUnderlay;
+extern vec2 nativeGbaSurfacePixels;
+extern vec2 nativeGbaCoefficients;
+vec4 effect(vec4 color, Image tex, vec2 uv, vec2 screen) {
+ vec4 pixel=Texel(tex,uv);
+ if(pixel.a==0.0)discard;
+ vec4 under=Texel(nativeGbaUnderlay,screen/nativeGbaSurfacePixels);
+ vec3 a=floor(clamp(pixel.rgb,0.0,1.0)*31.0+0.5);
+ vec3 b=floor(clamp(under.rgb,0.0,1.0)*31.0+0.5);
+ vec3 mixed=min(vec3(31.0),floor((a*nativeGbaCoefficients.x+b*nativeGbaCoefficients.y)/16.0));
+ return vec4(mixed/31.0,1.0);
+}
+]]
+function A.new()return setmetatable({},A)end
+function A:release()
+ if self.shader then self.shader:release();self.shader=nil end
+ if self.snapshot then self.snapshot:release();self.snapshot=nil end
+ self.width,self.height=nil,nil
+end
+function A:paint(eva,evb,draw)
+ assert(type(eva)=='number'and eva%1==0 and eva>=0 and eva<=16,'invalid native GBA source alpha')
+ assert(type(evb)=='number'and evb%1==0 and evb>=0 and evb<=16,'invalid native GBA target alpha')
+ assert(type(draw)=='function','native GBA alpha painter must be callable')
+ local g=love.graphics
+ local target=g.getCanvas()
+ if type(target)=='table'then target=target[1];if type(target)=='table'then target=target[1]end end
+ if not target then return false,'native GBA alpha requires an owned render surface'end
+ local w,h=target:getDimensions();local density=target:getDPIScale()
+ local pw,ph=math.floor(w*density+.5),math.floor(h*density+.5)
+ local ok,why=Scope.call(function()
+  if not self.snapshot or self.width~=pw or self.height~=ph then
+   local nextCanvas=g.newCanvas(pw,ph,{format='rgba8',dpiscale=1,msaa=0})
+   nextCanvas:setFilter('nearest','nearest')
+   local old=self.snapshot
+   self.snapshot,self.width,self.height=nextCanvas,pw,ph
+   if old then
+    -- Detach the old uniform binding before retiring the old target.
+    if self.shader then self.shader:send('nativeGbaUnderlay',nextCanvas)end
+    old:release()
+   end
+  end
+  if not self.shader then self.shader=g.newShader(A.SOURCE)end
+  local canvas={g.getCanvas()}
+  g.push('all')
+  g.setCanvas(self.snapshot);g.origin();g.setScissor();g.setShader()
+  g.setColor(1,1,1,1);g.setBlendMode('replace','premultiplied');g.clear(0,0,0,0)
+  g.draw(target,0,0,0,density,density)
+  -- Restore the target before its scissor/viewport-dependent state. OpenGL
+  -- bakes the active target's DPI when setScissor is restored by pop(all).
+  g.setCanvas(unpack(canvas));g.pop()
+  self.shader:send('nativeGbaUnderlay',self.snapshot)
+  self.shader:send('nativeGbaSurfacePixels',{pw,ph})
+  self.shader:send('nativeGbaCoefficients',{eva,evb})
+  g.setShader(self.shader);g.setColor(1,1,1,1)
+  g.setBlendMode('replace','premultiplied')
+  draw()
+ end)
+ return ok,why
+end
+return A
diff --git a/tests/engine/native_level_up_facade.lua b/tests/engine/native_level_up_facade.lua
new file mode 100644
index 000000000..74c2c8189
--- /dev/null
+++ b/tests/engine/native_level_up_facade.lua
@@ -0,0 +1,41 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+package.path='./?.lua;./?/init.lua;'..package.path
+local T=require('tests.modkit')
+local Battle=require('src.core.game3.battle')
+local Layer=require('src.core.game3.battle.level_up_streaks')
+local G=require('src.core.Game3')
+local original=package.loaded['src.core.Game'];local base=Layer.draw
+for _,edition in ipairs{'firered','leafgreen','emerald','ruby','sapphire'}do
+ local f=require('tools.battle-source-runtime.fixture').new(edition);local game=f.game
+ package.loaded['src.core.Game']=game
+ T.eq(base(),false,'source draw cannot invent a native admission')
+ local battle=f.fresh('TACKLE').battle;battle.enter=false;game.stack:push(battle)
+ local frame=battle.frame;local calls=0
+ Layer.draw=function(st)
+  T.eq(st,Battle.getState());base(st);base(st)
+  return false,nil,'source result'
+ end
+ local a,b,c=Layer._nativeDraw(battle,function(owner)T.eq(owner,battle);calls=calls+1 end)
+ T.eq(a,false);T.eq(b,nil);T.eq(c,'source result');T.eq(calls,1,'native layer is borrowed once')
+ T.eq(battle.frame,frame,'capture does not advance the native clock')
+ local depth=love.graphics.getStackDepth and love.graphics.getStackDepth()
+ Layer.draw=function()love.graphics.push('all');error('level-up source error')end
+ T.raises(function()Layer._nativeDraw(battle,function()end)end,'level-up source error')
+ if depth then T.eq(love.graphics.getStackDepth(),depth,'callback error unwinds leaked graphics pushes')end
+ Layer.draw=function()game.stack:push({});local ok,why=base();game.stack:pop();return ok,why end
+ calls=0
+ local ok,why=Layer._nativeDraw(battle,function()calls=calls+1 end)
+ T.eq(ok,false);T.eq(why,'native level-up presentation admission changed');T.eq(calls,0)
+ local seams=require('src.mods.ModSeams');local previous=G._callbackOwner()
+ Layer.draw=function()T.eq(G._callbackOwner(),'level_owner');return base()end
+ seams._journal[#seams._journal+1]={tbl=Layer,key='draw',after=Layer.draw,owner='level_owner'}
+ Layer._nativeDraw(battle,function()return true end)
+ T.eq(G._callbackOwner(),previous,'attribution restores caller owner');table.remove(seams._journal)
+ Layer.draw=base
+ local releases=0;battle._levelUpBlend={release=function()releases=releases+1 end}
+ game.stack:pop();T.eq(releases,1,'real native battle exit retires its owned alpha buffers')
+ T.eq(battle._levelUpBlend,nil);T.eq(base(),false,'retired native battle cannot paint')
+ Battle._service.release();f.close();G.release()
+end
+Layer.draw=base;package.loaded['src.core.Game']=original
+T.finish('native level-up draw admission, once-only borrowing and graphics ownership')
diff --git a/tests/engine/native_level_up_streaks.lua b/tests/engine/native_level_up_streaks.lua
new file mode 100644
index 000000000..12759cf2f
--- /dev/null
+++ b/tests/engine/native_level_up_streaks.lua
@@ -0,0 +1,66 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+package.path='./?.lua;./?/init.lua;'..package.path
+local T=require('tests.modkit')
+local Streaks=require('src.battle.Gen3LevelUpStreaks')
+local Art=require('src.import.Gen3LevelUpArt')
+local bit=require('bit')
+local ffi=require('ffi')
+local seed=ffi.new('uint32_t[1]')
+local function speed(index)
+ -- Independent integer C-width oracle; never consume the game's RNG.
+ seed[0]=ffi.new('uint64_t',index)*1103515245+24691
+ return bit.band(tonumber(seed[0]),63)+32
+end
+local previous,seen={},{}
+for frame=0,100 do
+ local rows={};local active,count=Streaks.sample(frame,function(x,y,index,velocity)
+  T.eq(velocity,speed(index),'native LCG low-bit arithmetic')
+  T.eq(x,bit.band(index*219,63)-32)
+  T.eq(y,32+bit.arshift(-velocity*(frame-2*(index-1)),4),'signed subpixel truncation')
+  T.check(y>=-32 and y<=32,'sprite retires beyond its actual boundary')
+  if previous[index]then T.check(y<=previous[index],'streak moves upward')end
+  rows[index]=y;seen[index]=true
+ end)
+ local expected=0
+ for index=1,18 do
+  local age=frame-2*(index-1)
+  local y=bit.arshift(-speed(index)*age,4)
+  if age>=0 and y>=-64 then expected=expected+1 end
+ end
+ T.eq(count,expected);T.eq(active,expected>0 or frame<34)
+ T.eq(Streaks.busy(frame),active,'queue completion uses the same native frames as drawing')
+ previous=rows
+end
+local n=0;for _ in pairs(seen)do n=n+1 end;T.eq(n,18,'all sprites are sampled without an admission cap')
+T.raises(function()Streaks.sample(-1,function()end)end,'invalid native streak frame')
+T.raises(function()Streaks.sample(0)end,'native streak visitor must be callable')
+for _,edition in ipairs{'firered','leafgreen'}do T.eq(Art.supports(edition),true)end
+for _,edition in ipairs{'emerald','ruby','sapphire','gold','unknown'}do
+ T.eq(Art.supports(edition),false,'a foreign cartridge is not assigned FRLG artwork')
+ T.eq(Art.read({version=edition}),nil)
+end
+local V=require('src.core.GameVersion');local previousVersion=V.get()
+local Sound=require('src.core.Sound');local play=Sound.playSe;local sounds=0
+Sound.playSe=function(data,name)T.eq(name,'SE_RS_SHOP');sounds=sounds+1 end
+for _,edition in ipairs{'firered','leafgreen'}do
+ V.set(edition)
+ local actor={mon={hp=10},isPlayer=true,position=0}
+ local battle={frame=0,player=actor,data={constants={gen3LevelUpStreaks={image='owned native resource'}}},queue={}}
+ function battle:battlerAt(index)T.eq(index,0);return actor end
+ Streaks.queue(battle,actor)
+ T.eq(#battle.queue,1);T.eq(battle.queue[1].gbaLevelUpStreaks,true)
+ T.eq(Streaks.start(battle,battle.queue[1]),true)
+ local steps=0
+ while Streaks.update(battle)do battle.frame=battle.frame+1;steps=steps+1;T.check(steps<100,'native effect finishes without a timeout extension')end
+ T.eq(battle._levelUpStreaks,nil);T.check(steps>34,'native queue holds through the final sprites')
+ actor.mon.hp=0;T.eq(Streaks.start(battle,battle.queue[1]),false,'fainted actors do not gain a visible streak effect')
+ actor.mon.hp=10;battle.picFx={[actor]={hidden=true}}
+ T.eq(Streaks.start(battle,battle.queue[1]),false,'hidden native sprites remain hidden')
+ battle.picFx=nil;battle.data.constants.gen3LevelUpStreaks=nil
+ T.eq(Streaks.start(battle,battle.queue[1]),false,'an absent native resource is never replaced with generic artwork')
+ local released=0;battle._levelUpBlend={release=function()released=released+1 end}
+ Streaks.release(battle);Streaks.release(battle);T.eq(released,1,'owned render buffers retire once')
+end
+T.eq(sounds,2,'native sound is triggered once per accepted effect')
+Sound.playSe=play;V.set(previousVersion)
+T.finish('native vertical streak timing, integer sampling and edition ownership')
diff --git a/tools/native-level-up-blend/conf.lua b/tools/native-level-up-blend/conf.lua
new file mode 100644
index 000000000..aa9245127
--- /dev/null
+++ b/tools/native-level-up-blend/conf.lua
@@ -0,0 +1,6 @@
+function love.conf(t)
+ t.identity=assert(os.getenv('POKEPORT_IDENTITY'));t.version='12.0'
+ t.window.width,t.window.height,t.window.vsync=160,96,0
+ t.modules.audio,t.modules.joystick,t.modules.physics=false,false,false
+ if t.graphics then t.graphics.renderers={assert(os.getenv('POKEPORT_GRAPHICS_BACKEND'))}end
+end
diff --git a/tools/native-level-up-blend/main.lua b/tools/native-level-up-blend/main.lua
new file mode 100644
index 000000000..d0232539b
--- /dev/null
+++ b/tools/native-level-up-blend/main.lua
@@ -0,0 +1,75 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+function love.errorhandler(err)io.stderr:write(tostring(err)..'\n');return function()return 1 end end
+local root=assert(os.getenv('NATIVE_BALL_ENGINE'))
+package.path=root..'/?.lua;'..root..'/?/init.lua;'..package.path
+local Alpha=require('src.render.NativeGbaAlpha')
+local g=love.graphics
+local checks=0
+local function check(ok,why)checks=checks+1;assert(ok,why)end
+function love.load()
+ check(love.filesystem.getIdentity():match('^oasc%-gen2recomp%-qa%-'),'owned QA identity')
+ local renderer=g.getRendererInfo()
+ check(renderer:lower():find(assert(os.getenv('POKEPORT_GRAPHICS_BACKEND')),1,true),'actual requested backend')
+ local blend=Alpha.new()
+ local borrowed=g.newShader('vec4 effect(vec4 c,Image t,vec2 uv,vec2 p){return Texel(t,uv)*c;}')
+ for _,dpi in ipairs{1,2}do
+  local pw,ph=16*dpi,8*dpi
+  local target=g.newCanvas(16,8,{format='rgba8',dpiscale=dpi,msaa=0})
+  local bg=love.image.newImageData(pw,ph);local fg=love.image.newImageData(pw,ph)
+  for y=0,ph-1 do for x=0,pw-1 do
+   bg:setPixel(x,y,((x*3+y)%32)/31,((x+y*7)%32)/31,((x*11+y*13)%32)/31,1)
+   fg:setPixel(x,y,((x*5+y*3)%32)/31,((x*7+y*5)%32)/31,((x+y*17)%32)/31,(x+y)%3==0 and 0 or 1)
+  end end
+  local under=g.newImage(bg);local image=g.newImage(fg)
+  under:setFilter('nearest','nearest');image:setFilter('nearest','nearest')
+  for _,coeff in ipairs{{12,6},{16,16},{0,16},{16,0},{0,0}}do
+   g.setCanvas(target);g.origin();g.setScissor();g.setShader();g.setColor(1,1,1,1)
+   g.setBlendMode('replace','premultiplied');g.clear(0,0,0,0);g.draw(under,0,0,0,1/dpi,1/dpi)
+   g.setCanvas()
+   local initial=g.readbackTexture(target)
+   check(initial:getWidth()==pw and initial:getHeight()==ph,'physical canvas dimensions')
+   for yy=0,ph-1 do for xx=0,pw-1 do
+    local actual={initial:getPixel(xx,yy)};local expected={bg:getPixel(xx,yy)}
+    for channel=1,4 do check(math.abs(actual[channel]-expected[channel])<=1.01/255,
+     ('underlay setup dpi%d x%d y%d c%d got%.8f expected%.8f'):format(dpi,xx,yy,channel,actual[channel],expected[channel]))end
+   end end
+   initial:release()
+   g.setCanvas(target)
+   g.setShader(borrowed);g.setScissor(2,1,10,5)
+   local before=g.getStackDepth()
+   local ok,why=blend:paint(coeff[1],coeff[2],function()
+    g.draw(image,0,0,0,1/dpi,1/dpi)
+    g.draw(image,0,0,0,1/dpi,1/dpi)
+   end)
+   check(ok,why);check(g.getShader()==borrowed,'caller shader restored')
+   check(g.getCanvas()==target,'borrowed render target retained');check(g.getStackDepth()==before,'graphics stack restored')
+   g.setCanvas();g.setShader();g.setScissor()
+   local pixels=g.readbackTexture(target)
+   for y=0,ph-1 do for x=0,pw-1 do
+    local underneath={bg:getPixel(x,y)};local source={fg:getPixel(x,y)}
+    local actual={pixels:getPixel(x,y)}
+    local inside=x>=2*dpi and x<12*dpi and y>=dpi and y<6*dpi and source[4]>0
+    for channel=1,4 do
+     local expected=underneath[channel]
+     if inside and channel<4 then
+      local a,b=math.floor(source[channel]*31+.5),math.floor(underneath[channel]*31+.5)
+      expected=math.min(31,math.floor((a*coeff[1]+b*coeff[2])/16))/31
+     end
+     check(math.abs(actual[channel]-expected)<=1.01/255,('native OAM alpha dpi%d eva%d evb%d x%d y%d c%d got%.8f expected%.8f'):format(dpi,coeff[1],coeff[2],x,y,channel,actual[channel],expected))
+    end
+   end end
+   pixels:release()
+  end
+  g.setCanvas(target);g.setShader(borrowed)
+  local before=g.getStackDepth()
+  local ok,why=blend:paint(12,6,function()g.push('all');error('intentional alpha callback failure')end)
+  check(not ok and tostring(why):find('intentional alpha callback failure',1,true),'callback error preserved')
+  check(g.getCanvas()==target and g.getShader()==borrowed and g.getStackDepth()==before,'error path restores caller graphics')
+  g.setCanvas();g.setShader()
+  target:release();image:release();under:release();bg:release();fg:release()
+ end
+ blend:release();blend:release();check(blend.snapshot==nil and blend.shader==nil,'owned resources retire idempotently')
+ g.setCanvas();check(blend:paint(12,6,function()end)==false,'window is not borrowed as a readable canvas')
+ borrowed:release()
+ print('NATIVE_LEVEL_BLEND_GPU_OK',renderer,checks);love.event.quit(0)
+end
diff --git a/tools/native-level-up/conf.lua b/tools/native-level-up/conf.lua
new file mode 100644
index 000000000..c714d9258
--- /dev/null
+++ b/tools/native-level-up/conf.lua
@@ -0,0 +1,6 @@
+function love.conf(t)
+ t.identity=assert(os.getenv('POKEPORT_IDENTITY'))
+ assert(t.identity:match('^oasc%-gen2recomp%-qa%-'))
+ t.version='12.0';t.window=false
+ t.modules.graphics=false;t.modules.audio=false;t.modules.joystick=false;t.modules.physics=false
+end
diff --git a/tools/native-level-up/main.lua b/tools/native-level-up/main.lua
new file mode 100644
index 000000000..b72d67f51
--- /dev/null
+++ b/tools/native-level-up/main.lua
@@ -0,0 +1,35 @@
+-- Copyright (c) 2026 Roxas2712. See LICENSE-ROXAS2712.md.
+io.stdout:setvbuf('no')
+local root=assert(os.getenv('NATIVE_TEXT_ENGINE'))
+package.path=root..'/?.lua;'..root..'/?/init.lua;'..package.path
+function love.errorhandler(err)print(debug.traceback(tostring(err),2));return function()return 1 end end
+local function read(path)local f=assert(io.open(path,'rb'));local s=f:read('*a');f:close();return s end
+function love.load()
+ assert(love.graphics==nil,'native art decoding must not initialize graphics')
+ local J=require('src.link.Json');local V=require('src.core.GameVersion')
+ local X=require('src.import.RomExtractorGen3');local Art=require('src.import.Gen3LevelUpArt')
+ local inputs=J.decode(read(assert(os.getenv('NATIVE_TEXT_INPUTS'))))
+ local results={editions={},pass=true,playerProfilesUsed=false,gpu=false}
+ for _,edition in ipairs{'firered','leafgreen','emerald','ruby','sapphire'}do
+  V.set(edition);local raw=read(inputs[edition])
+  local manifest=J.decode(read(root..'/'..V.info().manifest))
+  local x=X.new(raw,V.info(),manifest)
+  local record,why=Art.read(x)
+  if Art.supports(edition)then
+   assert(record,why);local image=Art.image(record)
+   assert(image:getWidth()==8 and image:getHeight()==16)
+   local bytes=image:getString()
+   results.editions[edition]={gfx=record.gfxOffset,palette=record.paletteOffset,
+    romSha1=record.romSha1,rgbaSha256=love.data.encode('string','hex',love.data.hash('sha256',bytes))}
+   -- Fingerprint gate precedes every palette/tile read, not just profile selection.
+   x.rom.data=string.char((raw:byte(1)+1)%256)..raw:sub(2)
+   assert(Art.read(x)==nil,'changed cartridge was accepted')
+   image:release()
+  else
+   assert(record==nil and why,'unsupported edition acquired FRLG artwork')
+   results.editions[edition]={supported=false}
+  end
+ end
+ local f=assert(io.open(assert(os.getenv('NATIVE_TEXT_RESULT')),'w'));f:write(J.encode(results));f:close()
+ print('NATIVE_LEVEL_ART_OK');love.event.quit(0)
+end

From a08fe1f0f1f62bb210eda44c6230733ee1054be2 Mon Sep 17 00:00:00 2001
From: Roxas2712 <Roxas2712@users.noreply.github.com>
Date: Tue, 27 Oct 2026 21:27:21 +0100
Subject: [PATCH 2/2] Allow shared native alpha programs with scoped uniform
 setup

---
 src/render/NativeGbaAlpha.lua | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/render/NativeGbaAlpha.lua b/src/render/NativeGbaAlpha.lua
index d7d2849d7..8cb84bde8 100644
--- a/src/render/NativeGbaAlpha.lua
+++ b/src/render/NativeGbaAlpha.lua
@@ -19,19 +19,29 @@ vec4 effect(vec4 color, Image tex, vec2 uv, vec2 screen) {
  return vec4(mixed/31.0,1.0);
 }
 ]]
-function A.new()return setmetatable({},A)end
+function A.new(source)
+ assert(source==nil or type(source)=='string','native GBA shader source must be a string')
+ return setmetatable({shaderSource=source},A)
+end
+function A:program()
+ if not self.shader then self.shader=love.graphics.newShader(self.shaderSource or A.SOURCE)end
+ return self.shader
+end
 function A:release()
  if self.shader then self.shader:release();self.shader=nil end
  if self.snapshot then self.snapshot:release();self.snapshot=nil end
  self.width,self.height=nil,nil
 end
-function A:paint(eva,evb,draw)
+function A:paint(eva,evb,draw,configure)
  assert(type(eva)=='number'and eva%1==0 and eva>=0 and eva<=16,'invalid native GBA source alpha')
  assert(type(evb)=='number'and evb%1==0 and evb>=0 and evb<=16,'invalid native GBA target alpha')
  assert(type(draw)=='function','native GBA alpha painter must be callable')
+ assert(configure==nil or type(configure)=='function','native GBA alpha configuration must be callable')
  local g=love.graphics
  local target=g.getCanvas()
- if type(target)=='table'then target=target[1];if type(target)=='table'then target=target[1]end end
+ if type(target)=='table'and not target.getDimensions then
+  target=target[1];if type(target)=='table'and not target.getDimensions then target=target[1]end
+ end
  if not target then return false,'native GBA alpha requires an owned render surface'end
  local w,h=target:getDimensions();local density=target:getDPIScale()
  local pw,ph=math.floor(w*density+.5),math.floor(h*density+.5)
@@ -47,7 +57,7 @@ function A:paint(eva,evb,draw)
     old:release()
    end
   end
-  if not self.shader then self.shader=g.newShader(A.SOURCE)end
+  self:program()
   local canvas={g.getCanvas()}
   g.push('all')
   g.setCanvas(self.snapshot);g.origin();g.setScissor();g.setShader()
@@ -59,6 +69,7 @@ function A:paint(eva,evb,draw)
   self.shader:send('nativeGbaUnderlay',self.snapshot)
   self.shader:send('nativeGbaSurfacePixels',{pw,ph})
   self.shader:send('nativeGbaCoefficients',{eva,evb})
+  if configure then configure(self.shader)end
   g.setShader(self.shader);g.setColor(1,1,1,1)
   g.setBlendMode('replace','premultiplied')
   draw()