Session 114 — Fix exports sprites bitmap (NUM_FRAMES + chemins HQN)

Probleme

Apres re-test visuel des sprites exportes par {@code WadConverter}, deux
bugs identifies :

1. bigbullet_f33.png (et frames 32+ de tous les objets) montraient des
   sprites « fantomes » : par exemple 4 bullets dans une grille 2×2,
   alors que c’est une seule bullet par frame. {@code glare/} exportait
   64 frames dont la moitie etait du contenu vole a l’objet voisin.

2. worm_f17.png et toutes les frames de worm = bruit visuel noir :
   le rendu HQN decodait des donnees 5-bit packed au lieu de 1 byte/pixel.

Sources analysees

• {@code defs.i} — STRUCTURE GLFT pour confirmer les offsets du LNK
• {@code leved303.amos::_GL_SETOBJFRAMES} — doc du format frame data
• {@code objdrawhires.s::draw_bitmap, draw_bitmap_lighted} — rendu standard vs HQN
• Inventaire {@code media/includes} et {@code media/hqn} (fichiers en double)

Cause racine 1 : NUM_FRAMES=64 incorrect

La structure GLFT_FrameData_l du LNK fait 30 objets x 256 bytes :

OFS_FRAME_DATA   = 0x39B0  (14768)
OFS_OBJECT_NAMES = 0x57B0  (22448)
diff             = 0x1E00  (7680 = 30 * 256)

Chaque frame = 8 bytes (LX, LY, LW/2, LH/2 en WORD), donc 256/8 = 32 frames
max par objet. Le commentaire de leved303.amos qui mentionnait « FRN (0..63) »
etait trompeur (probable vestige d’un format intermediaire jamais utilise).

Avec {@code NUM_FRAMES = 64}, {@code countFrames(objIdx)} et
{@code getFrameDesc(objIdx, frameIdx >= 32)} lisaient au-dela des 256 bytes
de l’objet et tombaient dans les donnees de l’objet suivant. Resultat :
les frames 32+ etaient en fait les frames 0+ des objets voisins, d’ou les
sprites fantomes.

Cause racine 2 : worm/robotright en double dans deux dossiers

media/includes/worm.wad     = 50.88 KB  (5-bit packed, format standard)
media/hqn/worm.wad          = 93.29 KB  (1 byte/pixel, format HQN)

media/includes/worm.256pal  = 2 KB      (32 brightness * 64 bytes)
media/hqn/worm.256pal       = 1 KB      (4 light types * 256 bytes)

{@code gatherWadSearchPaths} ajoutait {@code media/includes} avant
{@code media/hqn}, donc {@code findAndLoad(« worm.wad », …)} trouvait la
version 5-bit packed. Mais comme {@code worm} est dans {@code HQN_SPRITE_NAMES},
{@code renderFrameHqn} essayait de decoder 1 byte/pixel sur ces donnees,
produisant du bruit.

Les autres HQN ({@code ashnarg}, {@code insect}, {@code guard}, {@code priest},
{@code triclaw}) n’etaient pas affectes car ils n’existent QUE dans
{@code media/hqn/}.

Fixes

LnkParser.java : NUM_FRAMES 64 -> 32, avec javadoc detaillant le calcul
de la taille reelle de la section frame data et l’historique du bug.

WadConverter.java :
– {@code gatherWadSearchPaths(srcRes, preferHqn)} : nouveau parametre
{@code preferHqn} qui inverse l’ordre {@code includes/hqn} en favorisant
{@code hqn/} pour les sprites HQN.
– Boucle {@code extraAlienSprites} (worm, robotright) : utilise maintenant
{@code hqnSearchPaths} au lieu de {@code wadSearchPaths}.
– Nettoyage prealable du dossier de sortie {@code assets/Textures/objects}
pour supprimer les anciennes frames fantomes du dernier run buggy
(sans cela, glare_f32..f63 et bigbullet_f33 resteraient sur disque
apres re-export, polluant les checks visuels).
– Log enrichi : taille des fichiers WAD/PTR/256pal pour les sprites EXTRA
(utile pour verifier qu’on charge bien le bon fichier).

Validation attendue

Apres re-export par {@code ./gradlew convertWads} :

• assets/Textures/objects/glare/ : exactement 32 fichiers (au lieu de 64)
• assets/Textures/objects/bigbullet/ : plus de _f33.png avec 4 bullets
• assets/Textures/objects/worm/worm_f0.png : un vrai sprite de worm vert
• assets/Textures/objects/worm/ : ~32 frames (pas 20)
• Toutes les autres sprites (alien2, ashnarg, insect, guard, etc.) inchanges

Limitations connues (pas dans le scope)

• {@code robotright} reste tres desature (sepia/grey). Le lightType=0 utilise
  par {@code buildHqnPalsVl} pourrait ne pas correspondre a la palette
  prevue pour le robot. A investiguer si necessaire dans une session future.
• Les sprites GLARE ({@code glare/}, {@code explosion/}) apparaissent ternes
  car concus pour un rendu en blend additif au runtime. Pas un bug de
  l’export, mais a prendre en compte dans le materiel JME des billboards.