SnesLab - User contributions [en]

Dynamic Xtreme

2026-10-25T22:16:39Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme}}

Dynamic Xtreme is a tool for dynamic graphics and palettes in Super Mario World on the SNES, created by [[User:Anonimzwx|Anonimzwx]] as the successor to Dynamic Z and Dynamic X. Built for the ROM hacking community, it lets graphics and colors change in real time during gameplay. Its dynamic graphics system is flexible and modular, with a focus on performance.

A dynamic sprite loads resources, such as graphics or palettes, in real time during gameplay. A static sprite uses resources that were already loaded when the level began.

Dynamic Xtreme does not break the SNES hardware limits: it works within them, optimizing memory use and transfers to reduce their impact and make them much less noticeable during gameplay.

Its main features include:
* Real-time (on-the-fly) graphics and palette changes.
* The most powerful and flexible dynamic sprite system available for Super Mario World.
* An Advanced Drawing System that can draw any registered frame on screen, with full control over priority, layer, offsets, and properties.
* Advanced palette effects, including real-time changes to hue, saturation, brightness, color blending, smooth transitions, and individual RGB and HSL channels.
* Complete replacement of player graphics and palettes, supporting any Mario size, any number of frames, and any animation style.
* Yoshi graphics replacement using a layout like the original game's.
* Extensive NMI handler optimizations to maximize performance.

Dynamic Xtreme's features are selected during installation so a project can use only what it needs. Some have dependencies, compatibility issues, or restrictions on uninstalling them; check each option's warnings. The tool aims to make complex visual effects easier to implement in Super Mario World hacks while maintaining a high level of compatibility and stability.

== Project goals ==

Dynamic Xtreme's main goal is to make dynamic sprites easier to use and provide full support for real-time graphics, palette, and tilemap changes.

The project aims to make the most of the SNES without requiring advanced knowledge of the console's internal hardware. Traditional dynamic systems are often complex and rely heavily on technical concepts such as VRAM, CGRAM, OAM, and DMA. Dynamic Xtreme hides much of that complexity behind more modern, readable tools and formats that are easier to use.

Another main goal is to maintain high performance even in visually complex situations, allowing extensive use of dynamic graphics, palette effects, and advanced drawing systems without unnecessarily compromising performance.

Dynamic Xtreme also aims to make dynamic sprites as natural and straightforward to use as regular sprites. People focused on level design or content creation should be able to work with dynamic resources without constantly worrying about the system's internal technical limitations.

== Features ==

During installation, you can choose which features to enable. The names in parentheses match the installer options and <code>Settings.json</code>.

=== Graphics, poses, and palettes ===

{| class="wikitable"
! Feature !! Purpose
|-
| Graphics changes (<code>GraphicsChange</code>) || Allows graphics to be loaded during gameplay. This is the foundation for tile animations, level graphics changes, and dynamic poses.
|-
| Palette changes (<code>PalettesChange</code>) || Allows palettes to be loaded and managed during gameplay. Includes automatic palette assignment so sprites can share the same colors without loading them multiple times.
|-
| Dynamic poses (<code>DynamicPoses</code>) || Manages VRAM space as a pose cache: reuses loaded poses, shares them between entities, and chooses which ones to replace when more space is needed. This avoids unnecessary loads.
|-
| Pose drawing (<code>DrawingSystem</code>) || Draws both dynamic and static poses defined in DrawInfo files. Allows control over their tiles, position, flipping, palette, and drawing priority.
|-
| Palette effects (<code>PalettesEffects</code>) || Changes colors using RGB and HSL effects: tinting palettes, adjusting hue, saturation, or lightness, and making transitions between palettes. Effects can apply to individual resources or globally.
|}

Dynamic pose loading and drawing are separate systems: you can draw a static pose without loading its graphics dynamically.

=== Player and Yoshi ===

{| class="wikitable"
! Feature !! Purpose
|-
| Player features (<code>PlayerFeatures</code>) || Allows player graphics and palettes to be changed and adapts player drawing and pose loading for custom systems. Also allows the player to be hidden or dynamic uploads to be disabled. May conflict with patches that modify player graphics or palettes; read the installer warning before enabling it.
|-
| Yoshi features (<code>YoshiFeatures</code>) || Allows Yoshi's graphics to be changed while retaining the original pose layout. Requires <code>PlayerFeatures</code> and shares its compatibility restrictions.
|}

=== Memory and optimizations ===

These options reorganize some of the game's work to leave more time for graphics and palette transfers. NMI is the routine that updates the display during the interval between frames.

{| class="wikitable"
! Feature !! Purpose
|-
| Free the <code>$7E2000</code> area (<code>Free7E2000</code>) || On ROMs without SA-1, avoids keeping certain original player, Yoshi, and animation graphics in RAM and reads them from ROM instead. Dynamic Xtreme uses the recovered space for its internal variables; it is not freely available for other uses without reservation. This option does not apply to SA-1 ROMs.
|-
| Controller optimization (<code>ControllerOptimization</code>) || Moves controller processing out of NMI to leave more time for display updates.
|-
| Fixed color optimization (<code>FixedColorOptimization</code>) || Reduces NMI work for updating the fixed color used by the game's color math.
|-
| Kevin's Lunar Magic VRAM optimization (<code>KevinLMVRAMOptimization</code>) || Integrates Kevin's optimization for Lunar Magic VRAM updates and moves some of its processing out of NMI. Use this version instead of installing the original patch separately. Once installed, it must not be uninstalled: doing so can break the ROM.
|-
| Status bar optimization (<code>StatusBarOptimization</code>) || Reduces the original status bar's NMI work. Incompatible with resources that replace or modify it, such as custom status bars or patches that remove it.
|}

For options that may conflict with other resources and the RAM used by the system, see [[#Compatibility|Compatibility]].

Some features depend on others: <code>DynamicPoses</code> requires <code>GraphicsChange</code>; <code>PalettesEffects</code> requires <code>PalettesChange</code>; <code>PlayerFeatures</code> requires both graphics and palette changes; and <code>YoshiFeatures</code> requires <code>PlayerFeatures</code>.

== Quick Start ==

'''Quick installation guide:''' [[Dynamic_Xtreme_Quick_Start|Quick Start]]

== Tools and support ==

Pending

== Files and formats ==

'''Related article:''' [[Dynamic_Xtreme_files_and_formats|Dynamic Xtreme files and formats]]

== Dynamic sprite creation guide ==

To learn how to prepare, program, load, and draw a dynamic sprite, see the [[Dynamic_Xtreme_sprite_creation_guide|Dynamic Xtreme dynamic sprite creation guide]].

== Dynamic Xtreme with UberASM ==

The [[Dynamic_Xtreme_UberASM_guide|Dynamic Xtreme UberASM guide]] shows how to reserve palettes, configure dynamic sprite space and the per-frame data limit, create animations, change player graphics, and apply palette effects.

== API ==

The [[Dynamic_Xtreme_ASM_API|ASM API reference]] explains how to use Dynamic Xtreme's variables, defines, routines, and macros. It covers each call's inputs and results, with examples for poses, drawing, palettes, color effects, and graphics transfers, as well as multiplication and division macros.

== How the system works ==

The article on [[Dynamic_Xtreme_internal_workings|Dynamic Xtreme's internal workings]] explains the organization of NMI and game modes, graphics and palette loading, pose drawing, optimizations, the dynamic pose cache, and palette effects.

== Compatibility ==

In general, features without installer warnings do not usually have compatibility problems with other resources. These are:

* <code>GraphicsChange</code>
* <code>PalettesChange</code>
* <code>DynamicPoses</code>
* <code>DrawingSystem</code>
* <code>PalettesEffects</code>
* <code>Free7E2000</code>
* <code>ControllerOptimization</code>
* <code>FixedColorOptimization</code>

This does not guarantee that every resource combination will work: two pieces of code may still use the same RAM, the same VRAM space, or modify the same game routine. Also, <code>YoshiFeatures</code> requires <code>PlayerFeatures</code>, so the latter's restrictions still apply.

=== Features with compatibility restrictions ===

{| class="wikitable"
! Optional feature !! Possible conflicts and what to do
|-
| <code>PlayerFeatures</code> || May conflict with '''LX5's Powerups''', '''Player 8x8 tiles DMAer''', '''Player 32x32''', and other systems that replace player graphics or palette loading. '''Player Revolution''' is compatible. If your player system needs those original routines, leave this option disabled; you must also disable <code>YoshiFeatures</code>.
|-
| <code>YoshiFeatures</code> || Depends on <code>PlayerFeatures</code> and inherits its compatibility restrictions, even though it has no separate warning. If a resource is incompatible with <code>PlayerFeatures</code>, enabling only <code>YoshiFeatures</code> cannot avoid the conflict: leave both disabled.
|-
| <code>StatusBarOptimization</code> || Incompatible with resources that modify, replace, or remove the original status bar, such as '''LX5's DKC Style Status Bar''', '''Minimalistic Status Bar''', and '''Nuke Status Bar'''. Leave this optimization disabled if you use one of them.
|-
| <code>KevinLMVRAMOptimization</code> || Integrates Kevin's Lunar Magic VRAM optimization patch: use this version instead of installing the original separately. Its warning also states that it '''must not be uninstalled after installation''', because doing so can break the ROM. To revert it, restore a backup made before installation.
|}

These features are optional: leave a conflicting feature disabled and continue using Dynamic Xtreme's other systems, respecting their dependencies. Disabling an option does not undo another patch's changes or remove the uninstall restriction on <code>KevinLMVRAMOptimization</code>.

=== RAM usage ===

The main addresses are configured in <code>ASM/DXDefines.asm</code> inside the Dynamic Xtreme directory. In the repository, this is <code>DynamicXtremeLibrary/ASM/DXDefines.asm</code>.

The space used depends on the enabled features and whether the ROM uses SA-1. The following ranges include both endpoints and were calculated with '''all features that reserve RAM enabled''', <code>!VRAMTransferSize = 64</code>, and <code>!CGRAMTransferSize = 64</code>:

{| class="wikitable"
! Configuration !! <code>!Variables</code> block !! Size !! <code>!Variables2</code> block !! Size
|-
| LoROM with <code>Free7E2000</code> || <code>$7E2000–$7E2500</code> || <code>$0501</code>: 1281 bytes || <code>$7E2800–$7E3608</code> || <code>$0E09</code>: 3593 bytes
|-
| LoROM without <code>Free7E2000</code> || <code>$7FB440–$7FB940</code> || <code>$0501</code>: 1281 bytes || <code>$7F9C80–$7FAA88</code> || <code>$0E09</code>: 3593 bytes
|-
| SA-1 || <code>$40C000–$40C47E</code> || <code>$047F</code>: 1151 bytes || <code>$418AFF–$419907</code> || <code>$0E09</code>: 3593 bytes
|}

The two internal blocks total '''4874 bytes on LoROM''' and '''4744 bytes on SA-1'''. The difference comes from the drawing system's 130 bytes, which are reserved only on LoROM. The gap between the blocks is not automatically occupied.

Disabling a feature removes its conditional reservations and shifts the addresses that follow. Increasing <code>!VRAMTransferSize</code> or <code>!CGRAMTransferSize</code> also increases their table sizes.

==== Sprite tables ====

<code>DX_FreeRams</code> and <code>DX_FreeRams2</code> '''are not available for your own variables''': the sprite tables from <code>DynamicXSpritesTables.asm</code> and <code>MoreSpriteMiscs.asm</code> begin there. You must also reserve them when using those resources.

With the same configuration as the table above, their ranges are:

{| class="wikitable"
! Configuration !! Tables starting at <code>DX_FreeRams</code> !! Size !! Tables starting at <code>DX_FreeRams2</code> !! Size
|-
| LoROM with <code>Free7E2000</code> || <code>$7E2501–$7E26EC</code> || 492 bytes || <code>$7E3609–$7E3824</code> || 540 bytes
|-
| LoROM without <code>Free7E2000</code> || <code>$7FB941–$7FBB2C</code> || 492 bytes || <code>$7FAC82–$7FAE9D</code> || 540 bytes
|-
| SA-1 || <code>$40C47F–$40C6D8</code> || 602 bytes || <code>$419908–$419BCD</code> || 710 bytes
|}

Including these tables, the described space totals '''5906 bytes on LoROM''' and '''6056 bytes on SA-1'''. Tables are calculated for 12 normal sprites on LoROM and 22 on SA-1, plus the corresponding cluster, extended, and smoke slots.

Normally, <code>DX_FreeRams2</code> starts immediately after the second internal block. On LoROM without <code>Free7E2000</code>, it is placed separately using <code>!Variables3 = $7FAC82</code>, so its tables do not immediately follow <code>!Variables2</code>.

Dynamic Xtreme also uses the existing fixed color and palette mirrors: <code>$7E0701</code> (2 bytes) and <code>$7E0703</code> (512 bytes) on LoROM. Their declared SA-1 addresses are <code>$406701</code> and <code>$006703</code>. These are neither additional reservations within the blocks above nor free addresses for your code.

==== Relocating RAM to resolve a conflict ====

'''Warning:''' relocating these variables requires knowing which address to choose and accounting for the full memory footprint. A free starting address is not enough: the entire block must fit, and the routines must be able to access it. If you are unfamiliar with this, consult someone experienced before changing the addresses.

If another resource uses any of these areas, you can edit '''<code>ASM/DXDefines.asm</code>''' to make Dynamic Xtreme use other available space in your ROM hack.

* Change <code>!Variables</code> and <code>!Variables2</code> in the configuration matching your ROM: LoROM with <code>Free7E2000</code>, LoROM without it, or SA-1.
* On LoROM without <code>Free7E2000</code>, also check <code>!Variables3</code>, which determines where the <code>DX_FreeRams2</code> tables begin.
* Reserve enough space for the entire block and the sprite tables that follow. A free first address alone is not enough.
* Respect the memory map and the banks required by the routines. Not every free address works with every type of access.
* After changing the addresses, reinstall Dynamic Xtreme and reinsert PIXI, UberASM, and any other resources that use its defines.

With <code>Free7E2000</code>, Dynamic Xtreme uses the RAM recovered by relocating the original graphics; do not share it with other resources without checking which part is used. Without that option, the alternative addresses may overlap those of other common resources. SA-1 uses its own addresses and disables <code>Free7E2000</code>.

Edit the file in the '''ASM''' directory, not the generated copies in <code>ExtraDefines</code> or <code>Patch/ExtraDefines</code>: those copies are regenerated during installation.

== Resources made with Dynamic Xtreme ==

Resources developed for Dynamic Xtreme are not usually published on traditional sites such as SMW Central, because many depend directly on the framework and its advanced systems.

Instead, Dynamic Xtreme resources, examples, systems, and related projects are mainly collected at:

https://snestorage.dev

There you can find sprites, player systems, graphical effects, technical examples, and other resources designed specifically for Dynamic Xtreme.

== Conclusion ==

Dynamic Xtreme aims to modernize and simplify dynamic systems in Super Mario World, offering more flexible, powerful, and accessible tools while retaining compatibility and advanced control.

The project continues to evolve with new optimizations, formats, and tools for both experienced users and people just starting to work with dynamic graphics on SNES.

Dynamic Xtreme's main aim is to support increasingly complex resources and systems while keeping the workflow cleaner, easier to maintain, and more accessible to the community.

es/Dynamic Xtreme

2026-10-25T22:16:11Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme}}

Dynamic Xtreme es una herramienta de soporte dinámico avanzada para Super Mario World en el SNES, creada por [[User:Anonimzwx|Anonimzwx]] y sucesora de Dynamic Z y Dynamic X. Desarrollada para la comunidad de ROM hacking, permite realizar cambios gráficos y de paletas en tiempo real durante la ejecución del juego. La herramienta se centra en ofrecer un sistema completo y flexible de gráficos dinámicos, con énfasis en el rendimiento y la modularidad.

Un sprite dinámico carga recursos, como gráficos o paletas, en tiempo real durante el juego. En cambio, un sprite estático utiliza los recursos que ya estaban cargados al comenzar el nivel.

Dynamic Xtreme no rompe los límites del hardware de SNES: trabaja dentro de ellos y optimiza el uso de la memoria y las transferencias para reducir su impacto y hacer que sean mucho menos perceptibles durante el juego.

Entre sus características principales se incluyen:
* Cambios gráficos y de paleta en tiempo real (on-the-fly).
* El sistema de Dynamic Sprite más potente y flexible disponible para Super Mario World.
* Advanced Drawing System, que permite dibujar cualquier frame registrado en pantalla con control total sobre prioridad, capa, desplazamiento (offset) y propiedades.
* Efectos de paleta avanzados, que incluyen modificación en tiempo real mediante tono (hue), saturación, brillo, fusión de colores, transiciones suaves y control individual de canales RGB y HSL.
* Reemplazo completo de gráficos y paletas del jugador, compatible con cualquier tamaño de Mario, cualquier cantidad de frames y cualquier estilo de animación.
* Reemplazo de gráficos de Yoshi usando un layout como el del juego original.
* Optimizaciones intensivas en el NMI-handler para maximizar el rendimiento.

Las funciones de Dynamic Xtreme se seleccionan durante la instalación para utilizar solo las que necesita el proyecto. Algunas tienen dependencias, problemas de compatibilidad o restricciones para desinstalarlas; revisa las advertencias de cada opción. La herramienta fue creada con el objetivo de facilitar la implementación de efectos visuales complejos en hacks de Super Mario World manteniendo un alto nivel de compatibilidad y estabilidad.

== Objetivos del proyecto ==

El principal objetivo de Dynamic Xtreme es facilitar el uso de sprites dinámicos y ofrecer un soporte completo para cambios de gráficos, paletas y tilemaps en tiempo real.

El proyecto busca aprovechar al máximo el potencial del SNES sin requerir que el usuario tenga conocimientos avanzados sobre el hardware interno de la consola. Muchos sistemas dinámicos tradicionales suelen ser complejos y dependen fuertemente de conceptos técnicos como VRAM, CGRAM, OAM o DMA. Dynamic Xtreme intenta abstraer gran parte de esa complejidad mediante herramientas y formatos más modernos, legibles y fáciles de utilizar.

Otro de los objetivos principales del proyecto es mantener un alto rendimiento incluso en situaciones visualmente complejas, permitiendo el uso intensivo de gráficos dinámicos, efectos de paletas y sistemas avanzados de renderizado sin comprometer innecesariamente la performance.

Además, Dynamic Xtreme busca que los sprites dinámicos puedan utilizarse de una forma tan natural y sencilla como si fueran sprites normales. La idea es que las personas enfocadas en level design o creación de contenido no necesiten preocuparse constantemente por las limitaciones técnicas internas del sistema y puedan trabajar con recursos dinámicos de forma transparente y práctica.

== Funcionalidades ==

Durante la instalación puedes elegir qué funcionalidades habilitar. Los nombres entre paréntesis corresponden a las opciones del instalador y de <code>Settings.json</code>.

=== Gráficos, poses y paletas ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Cambios de gráficos (<code>GraphicsChange</code>) || Permite cargar gráficos durante el juego. Es la base para las animaciones de tiles, los cambios de gráficos del nivel y las poses dinámicas.
|-
| Cambios de paletas (<code>PalettesChange</code>) || Permite cargar y administrar paletas durante el juego. Incluye la asignación automática de paletas para que los sprites puedan compartir los mismos colores sin cargarlos varias veces.
|-
| Poses dinámicas (<code>DynamicPoses</code>) || Administra el espacio de VRAM como una caché de poses: reutiliza las que ya están cargadas, permite compartirlas entre entidades y elige cuáles reemplazar cuando hace falta espacio. Así evita cargas innecesarias.
|-
| Dibujo de poses (<code>DrawingSystem</code>) || Dibuja las poses definidas en archivos DrawInfo, tanto dinámicas como estáticas. Permite controlar sus tiles, posición, volteo, paleta y prioridad de dibujo.
|-
| Efectos de paleta (<code>PalettesEffects</code>) || Permite cambiar colores mediante efectos RGB y HSL: teñir paletas, modificar tono, saturación o luminosidad, y realizar transiciones entre paletas. Pueden aplicarse a recursos individuales o como un efecto global.
|}

La carga de poses dinámicas y el dibujo son sistemas separados: puedes dibujar una pose estática sin cargar sus gráficos dinámicamente.

=== Jugador y Yoshi ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Funciones del jugador (<code>PlayerFeatures</code>) || Permite cambiar los gráficos y paletas del jugador y adaptar su dibujo y carga de poses a sistemas personalizados. También permite ocultarlo o desactivar sus cargas dinámicas. Puede entrar en conflicto con parches que modifican los gráficos o paletas del jugador; revisa la advertencia del instalador antes de habilitarla.
|-
| Funciones de Yoshi (<code>YoshiFeatures</code>) || Permite cambiar los gráficos de Yoshi manteniendo la organización de sus poses originales. Requiere <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad.
|}

=== Memoria y optimizaciones ===

Estas opciones reorganizan parte del trabajo del juego para dejar más tiempo disponible para las cargas de gráficos y paletas. NMI es la rutina que realiza las actualizaciones de pantalla durante la pausa entre un frame y el siguiente.

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Liberar el área <code>$7E2000</code> (<code>Free7E2000</code>) || En ROMs sin SA-1, evita mantener en RAM ciertos gráficos originales del jugador, Yoshi y animaciones, y permite leerlos desde ROM. Dynamic Xtreme utiliza el espacio recuperado para sus variables internas; no queda libre para usarlo sin reservar. Esta opción no se aplica a ROMs con SA-1.
|-
| Optimización del control (<code>ControllerOptimization</code>) || Mueve el procesamiento del control fuera de NMI para dejar más tiempo disponible para las actualizaciones de pantalla.
|-
| Optimización del color fijo (<code>FixedColorOptimization</code>) || Reduce el trabajo de NMI relacionado con la actualización del color fijo que utiliza el juego para sus mezclas de color.
|-
| Optimización de VRAM de Lunar Magic de Kevin (<code>KevinLMVRAMOptimization</code>) || Integra la optimización de Kevin para las actualizaciones de VRAM de Lunar Magic y mueve parte de su procesamiento fuera de NMI. Utiliza esta versión en lugar del parche original por separado. Una vez instalada, no debe desinstalarse: hacerlo puede dañar el funcionamiento de la ROM.
|-
| Optimización de la barra de estado (<code>StatusBarOptimization</code>) || Reduce el trabajo de NMI de la barra de estado original. No es compatible con recursos que la reemplazan o modifican, como barras de estado personalizadas o parches que la eliminan.
|}

Para revisar qué opciones pueden entrar en conflicto con otros recursos y qué RAM utiliza el sistema, consulta [[#Compatibilidad|Compatibilidad]].

Algunas funcionalidades necesitan otras: <code>DynamicPoses</code> requiere <code>GraphicsChange</code>; <code>PalettesEffects</code> requiere <code>PalettesChange</code>; <code>PlayerFeatures</code> necesita ambas opciones de cambios gráficos y de paletas; y <code>YoshiFeatures</code> requiere <code>PlayerFeatures</code>.

== Quick Start ==

'''Guía rápida de instalación:''' [[es/Dynamic_Xtreme_Quick_Start|Quick Start]]

== Herramientas y Soporte ==

Pendiente

== Archivos y formatos ==

'''Artículo relacionado:''' [[es/Dynamic_Xtreme_files_and_formats|Archivos y Formatos de Dynamic Xtreme]]

== Guía de creación de sprites dinámicos ==

Para aprender a preparar, programar, cargar y dibujar un sprite dinámico, consulta la [[es/Dynamic_Xtreme_sprite_creation_guide|guía de creación de sprites dinámicos con Dynamic Xtreme]].

== Dynamic Xtreme con UberASM ==

La [[es/Dynamic_Xtreme_UberASM_guide|guía de Dynamic Xtreme con UberASM]] muestra cómo reservar paletas, configurar el espacio para sprites dinámicos y el límite de datos por frame, crear animaciones, cambiar gráficos del jugador y aplicar efectos de paleta.

== API ==

La [[es/Dynamic_Xtreme_ASM_API|referencia de la API ASM]] explica cómo utilizar las variables, los defines, las rutinas y las macros de Dynamic Xtreme. Incluye los datos que necesita cada llamada, sus resultados y ejemplos de uso para trabajar con poses, dibujo, paletas, efectos de color y transferencias de gráficos, además de las macros de multiplicación y división.

== Funcionamiento interno del sistema ==

El artículo sobre el [[es/Dynamic_Xtreme_internal_workings|funcionamiento interno de Dynamic Xtreme]] explica cómo se organizan NMI y los game modes, las cargas de gráficos y paletas, el dibujo de poses, las optimizaciones, la caché de poses dinámicas y los efectos de paleta.

== Compatibilidad ==

En general, las funcionalidades que no muestran warnings en el instalador no suelen presentar problemas de incompatibilidad con otros recursos. Estas son:

* <code>GraphicsChange</code>
* <code>PalettesChange</code>
* <code>DynamicPoses</code>
* <code>DrawingSystem</code>
* <code>PalettesEffects</code>
* <code>Free7E2000</code>
* <code>ControllerOptimization</code>
* <code>FixedColorOptimization</code>

Esto no garantiza que cualquier combinación de recursos funcione: dos códigos todavía pueden utilizar la misma RAM, el mismo espacio de VRAM o modificar la misma rutina del juego. Además, <code>YoshiFeatures</code> necesita <code>PlayerFeatures</code>, por lo que también debes considerar las restricciones de esta última.

=== Funcionalidades con restricciones de compatibilidad ===

{| class="wikitable"
! Funcionalidad opcional !! Posibles conflictos y qué hacer
|-
| <code>PlayerFeatures</code> || Puede entrar en conflicto con '''LX5's Powerups''', '''Player 8x8 tiles DMAer''', '''Player 32x32''' y otros sistemas que reemplazan la carga de gráficos o paletas del jugador. '''Player Revolution''' sí es compatible. Si tu sistema de jugador necesita esas rutinas originales, deja esta opción deshabilitada; también tendrás que deshabilitar <code>YoshiFeatures</code>.
|-
| <code>YoshiFeatures</code> || Depende de <code>PlayerFeatures</code> y hereda sus restricciones de compatibilidad, aunque no muestre un warning propio. Si otro recurso es incompatible con <code>PlayerFeatures</code>, no puedes evitar ese conflicto habilitando únicamente <code>YoshiFeatures</code>: debes dejar ambas deshabilitadas.
|-
| <code>StatusBarOptimization</code> || No es compatible con recursos que modifican, reemplazan o eliminan la barra de estado original, como '''LX5's DKC Style Status Bar''', '''Minimalistic Status Bar''' y '''Nuke Status Bar'''. Si utilizas uno de ellos, deja esta optimización deshabilitada.
|-
| <code>KevinLMVRAMOptimization</code> || Integra el parche de optimización de VRAM de Lunar Magic de Kevin: utiliza esta versión en lugar del parche original por separado. Su warning también indica que '''no debe desinstalarse después de instalarla''', porque hacerlo puede romper el funcionamiento de la ROM. Si necesitas revertirla, restaura una copia de seguridad anterior a su instalación.
|}

Estas funcionalidades son opcionales: puedes dejar deshabilitada la que entra en conflicto y seguir utilizando los demás sistemas de Dynamic Xtreme, respetando sus dependencias. Deshabilitar una opción no deshace los cambios de otro parche ni elimina la restricción de desinstalación de <code>KevinLMVRAMOptimization</code>.

=== Espacios de RAM utilizados ===

Las direcciones principales se configuran en <code>ASM/DXDefines.asm</code>, dentro de la carpeta de Dynamic Xtreme. En el repositorio, ese archivo corresponde a <code>DynamicXtremeLibrary/ASM/DXDefines.asm</code>.

El espacio utilizado depende de las funcionalidades habilitadas y de si la ROM utiliza SA-1. Los siguientes rangos incluyen el primer y el último byte y están calculados con '''todas las funcionalidades que reservan RAM habilitadas''', <code>!VRAMTransferSize = 64</code> y <code>!CGRAMTransferSize = 64</code>:

{| class="wikitable"
! Configuración !! Bloque <code>!Variables</code> !! Tamaño !! Bloque <code>!Variables2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2000–$7E2500</code> || <code>$0501</code>: 1281 bytes || <code>$7E2800–$7E3608</code> || <code>$0E09</code>: 3593 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB440–$7FB940</code> || <code>$0501</code>: 1281 bytes || <code>$7F9C80–$7FAA88</code> || <code>$0E09</code>: 3593 bytes
|-
| SA-1 || <code>$40C000–$40C47E</code> || <code>$047F</code>: 1151 bytes || <code>$418AFF–$419907</code> || <code>$0E09</code>: 3593 bytes
|}

Los dos bloques internos suman '''4874 bytes en LoROM''' y '''4744 bytes en SA-1'''. La diferencia se debe a los 130 bytes del sistema de dibujo que solo se reservan en LoROM. No se ocupa automáticamente el espacio que queda entre los bloques.

Al deshabilitar una funcionalidad se eliminan sus reservas condicionales y cambian las direcciones posteriores. Aumentar <code>!VRAMTransferSize</code> o <code>!CGRAMTransferSize</code> también aumenta el tamaño de sus tablas.

==== Tablas utilizadas por los sprites ====

<code>DX_FreeRams</code> y <code>DX_FreeRams2</code> '''no son espacios disponibles para escribir variables propias''': a partir de esas posiciones se ubican las tablas de sprites de <code>DynamicXSpritesTables.asm</code> y <code>MoreSpriteMiscs.asm</code>. También debes reservarlas si utilizas esos recursos.

Con la misma configuración de la tabla anterior, sus rangos son:

{| class="wikitable"
! Configuración !! Tablas desde <code>DX_FreeRams</code> !! Tamaño !! Tablas desde <code>DX_FreeRams2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2501–$7E26EC</code> || 492 bytes || <code>$7E3609–$7E3824</code> || 540 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB941–$7FBB2C</code> || 492 bytes || <code>$7FAC82–$7FAE9D</code> || 540 bytes
|-
| SA-1 || <code>$40C47F–$40C6D8</code> || 602 bytes || <code>$419908–$419BCD</code> || 710 bytes
|}

Incluyendo estas tablas, el espacio descrito suma '''5906 bytes en LoROM''' y '''6056 bytes en SA-1'''. Las tablas se calculan para 12 sprites normales en LoROM y 22 en SA-1, además de los slots de cluster, extended y smoke correspondientes.

Normalmente, <code>DX_FreeRams2</code> comienza justo después del segundo bloque interno. En LoROM sin <code>Free7E2000</code> se coloca por separado mediante <code>!Variables3 = $7FAC82</code>; por eso sus tablas no empiezan inmediatamente después de <code>!Variables2</code>.

Dynamic Xtreme también utiliza los espejos existentes del color fijo y de la paleta: <code>$7E0701</code> (2 bytes) y <code>$7E0703</code> (512 bytes) en LoROM. En SA-1 sus direcciones declaradas son <code>$406701</code> y <code>$006703</code>. No son reservas adicionales dentro de los bloques anteriores ni direcciones libres para tus códigos.

==== Reubicar la RAM si hay un conflicto ====

'''Advertencia:''' para reubicar estas variables debes saber qué dirección elegir y considerar el tamaño completo del espacio de memoria que utiliza el sistema. No basta con que una dirección esté libre: debe haber espacio suficiente y las rutinas deben poder acceder a él. Si no tienes conocimientos sobre esto, consulta con alguien que los tenga antes de modificar las direcciones.

Si otro recurso utiliza alguno de estos espacios, puedes modificar '''<code>ASM/DXDefines.asm</code>''' para hacer que Dynamic Xtreme utilice otras zonas disponibles de tu romhack.

* Cambia <code>!Variables</code> y <code>!Variables2</code> en la configuración correspondiente a tu ROM: LoROM con <code>Free7E2000</code>, LoROM sin esa opción o SA-1.
* En LoROM sin <code>Free7E2000</code>, revisa también <code>!Variables3</code>, que determina dónde empiezan las tablas de <code>DX_FreeRams2</code>.
* Reserva espacio suficiente para el bloque completo y las tablas de sprites que le siguen. No basta con que la primera dirección esté libre.
* Respeta el mapa de memoria y los bancos que necesitan las rutinas. No cualquier dirección libre sirve para cualquier acceso.
* Después de cambiar las direcciones, reinstala Dynamic Xtreme y vuelve a insertar PIXI, UberASM y los demás recursos que utilicen sus defines.

Con <code>Free7E2000</code>, Dynamic Xtreme aprovecha el área de RAM que recupera al reubicar los gráficos originales; no la compartas con otros recursos sin comprobar qué parte utiliza. Sin esa opción, las direcciones alternativas pueden coincidir con las de otros recursos habituales. SA-1 utiliza sus propias direcciones y desactiva <code>Free7E2000</code>.

Modifica el archivo de la carpeta '''ASM''', no las copias generadas en <code>ExtraDefines</code> o <code>Patch/ExtraDefines</code>: esas copias se regeneran durante la instalación.

== Recursos hechos con Dynamic Xtreme ==

La mayoría de los recursos desarrollados para Dynamic Xtreme no suelen publicarse en sitios tradicionales como SMW Central debido a que muchos de ellos dependen directamente del framework y sus sistemas avanzados.

En su lugar, los recursos, ejemplos, sistemas y proyectos relacionados con Dynamic Xtreme se encuentran recopilados principalmente en:

https://snestorage.dev

Allí es posible encontrar sprites, sistemas de jugador, efectos gráficos, ejemplos técnicos y otros recursos diseñados específicamente para trabajar con Dynamic Xtreme.

== Conclusión ==

Dynamic Xtreme es un proyecto orientado a modernizar y simplificar el uso de sistemas dinámicos en Super Mario World, ofreciendo herramientas más flexibles, potentes y fáciles de utilizar sin perder compatibilidad ni control avanzado.

El proyecto continúa evolucionando constantemente con nuevas optimizaciones, formatos y herramientas orientadas tanto a usuarios avanzados como a personas que recién comienzan a trabajar con gráficos dinámicos en SNES.

La intención principal de Dynamic Xtreme es permitir la creación de recursos y sistemas cada vez más complejos, manteniendo al mismo tiempo un workflow más limpio, mantenible y accesible para la comunidad.

es/Dynamic Xtreme

2026-10-25T22:14:47Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme}}

Dynamic Xtreme es una herramienta de soporte dinámico avanzada para Super Mario World en el SNES, creada por anonimzwx y sucesora de Dynamic Z y Dynamic X. Desarrollada para la comunidad de ROM hacking, permite realizar cambios gráficos y de paletas en tiempo real durante la ejecución del juego. La herramienta se centra en ofrecer un sistema completo y flexible de gráficos dinámicos, con énfasis en el rendimiento y la modularidad.

Un sprite dinámico carga recursos, como gráficos o paletas, en tiempo real durante el juego. En cambio, un sprite estático utiliza los recursos que ya estaban cargados al comenzar el nivel.

Dynamic Xtreme no rompe los límites del hardware de SNES: trabaja dentro de ellos y optimiza el uso de la memoria y las transferencias para reducir su impacto y hacer que sean mucho menos perceptibles durante el juego.

Entre sus características principales se incluyen:
* Cambios gráficos y de paleta en tiempo real (on-the-fly).
* El sistema de Dynamic Sprite más potente y flexible disponible para Super Mario World.
* Advanced Drawing System, que permite dibujar cualquier frame registrado en pantalla con control total sobre prioridad, capa, desplazamiento (offset) y propiedades.
* Efectos de paleta avanzados, que incluyen modificación en tiempo real mediante tono (hue), saturación, brillo, fusión de colores, transiciones suaves y control individual de canales RGB y HSL.
* Reemplazo completo de gráficos y paletas del jugador, compatible con cualquier tamaño de Mario, cualquier cantidad de frames y cualquier estilo de animación.
* Reemplazo de gráficos de Yoshi usando un layout como el del juego original.
* Optimizaciones intensivas en el NMI-handler para maximizar el rendimiento.

Las funciones de Dynamic Xtreme se seleccionan durante la instalación para utilizar solo las que necesita el proyecto. Algunas tienen dependencias, problemas de compatibilidad o restricciones para desinstalarlas; revisa las advertencias de cada opción. La herramienta fue creada con el objetivo de facilitar la implementación de efectos visuales complejos en hacks de Super Mario World manteniendo un alto nivel de compatibilidad y estabilidad.

== Objetivos del proyecto ==

El principal objetivo de Dynamic Xtreme es facilitar el uso de sprites dinámicos y ofrecer un soporte completo para cambios de gráficos, paletas y tilemaps en tiempo real.

El proyecto busca aprovechar al máximo el potencial del SNES sin requerir que el usuario tenga conocimientos avanzados sobre el hardware interno de la consola. Muchos sistemas dinámicos tradicionales suelen ser complejos y dependen fuertemente de conceptos técnicos como VRAM, CGRAM, OAM o DMA. Dynamic Xtreme intenta abstraer gran parte de esa complejidad mediante herramientas y formatos más modernos, legibles y fáciles de utilizar.

Otro de los objetivos principales del proyecto es mantener un alto rendimiento incluso en situaciones visualmente complejas, permitiendo el uso intensivo de gráficos dinámicos, efectos de paletas y sistemas avanzados de renderizado sin comprometer innecesariamente la performance.

Además, Dynamic Xtreme busca que los sprites dinámicos puedan utilizarse de una forma tan natural y sencilla como si fueran sprites normales. La idea es que las personas enfocadas en level design o creación de contenido no necesiten preocuparse constantemente por las limitaciones técnicas internas del sistema y puedan trabajar con recursos dinámicos de forma transparente y práctica.

== Funcionalidades ==

Durante la instalación puedes elegir qué funcionalidades habilitar. Los nombres entre paréntesis corresponden a las opciones del instalador y de <code>Settings.json</code>.

=== Gráficos, poses y paletas ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Cambios de gráficos (<code>GraphicsChange</code>) || Permite cargar gráficos durante el juego. Es la base para las animaciones de tiles, los cambios de gráficos del nivel y las poses dinámicas.
|-
| Cambios de paletas (<code>PalettesChange</code>) || Permite cargar y administrar paletas durante el juego. Incluye la asignación automática de paletas para que los sprites puedan compartir los mismos colores sin cargarlos varias veces.
|-
| Poses dinámicas (<code>DynamicPoses</code>) || Administra el espacio de VRAM como una caché de poses: reutiliza las que ya están cargadas, permite compartirlas entre entidades y elige cuáles reemplazar cuando hace falta espacio. Así evita cargas innecesarias.
|-
| Dibujo de poses (<code>DrawingSystem</code>) || Dibuja las poses definidas en archivos DrawInfo, tanto dinámicas como estáticas. Permite controlar sus tiles, posición, volteo, paleta y prioridad de dibujo.
|-
| Efectos de paleta (<code>PalettesEffects</code>) || Permite cambiar colores mediante efectos RGB y HSL: teñir paletas, modificar tono, saturación o luminosidad, y realizar transiciones entre paletas. Pueden aplicarse a recursos individuales o como un efecto global.
|}

La carga de poses dinámicas y el dibujo son sistemas separados: puedes dibujar una pose estática sin cargar sus gráficos dinámicamente.

=== Jugador y Yoshi ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Funciones del jugador (<code>PlayerFeatures</code>) || Permite cambiar los gráficos y paletas del jugador y adaptar su dibujo y carga de poses a sistemas personalizados. También permite ocultarlo o desactivar sus cargas dinámicas. Puede entrar en conflicto con parches que modifican los gráficos o paletas del jugador; revisa la advertencia del instalador antes de habilitarla.
|-
| Funciones de Yoshi (<code>YoshiFeatures</code>) || Permite cambiar los gráficos de Yoshi manteniendo la organización de sus poses originales. Requiere <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad.
|}

=== Memoria y optimizaciones ===

Estas opciones reorganizan parte del trabajo del juego para dejar más tiempo disponible para las cargas de gráficos y paletas. NMI es la rutina que realiza las actualizaciones de pantalla durante la pausa entre un frame y el siguiente.

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Liberar el área <code>$7E2000</code> (<code>Free7E2000</code>) || En ROMs sin SA-1, evita mantener en RAM ciertos gráficos originales del jugador, Yoshi y animaciones, y permite leerlos desde ROM. Dynamic Xtreme utiliza el espacio recuperado para sus variables internas; no queda libre para usarlo sin reservar. Esta opción no se aplica a ROMs con SA-1.
|-
| Optimización del control (<code>ControllerOptimization</code>) || Mueve el procesamiento del control fuera de NMI para dejar más tiempo disponible para las actualizaciones de pantalla.
|-
| Optimización del color fijo (<code>FixedColorOptimization</code>) || Reduce el trabajo de NMI relacionado con la actualización del color fijo que utiliza el juego para sus mezclas de color.
|-
| Optimización de VRAM de Lunar Magic de Kevin (<code>KevinLMVRAMOptimization</code>) || Integra la optimización de Kevin para las actualizaciones de VRAM de Lunar Magic y mueve parte de su procesamiento fuera de NMI. Utiliza esta versión en lugar del parche original por separado. Una vez instalada, no debe desinstalarse: hacerlo puede dañar el funcionamiento de la ROM.
|-
| Optimización de la barra de estado (<code>StatusBarOptimization</code>) || Reduce el trabajo de NMI de la barra de estado original. No es compatible con recursos que la reemplazan o modifican, como barras de estado personalizadas o parches que la eliminan.
|}

Para revisar qué opciones pueden entrar en conflicto con otros recursos y qué RAM utiliza el sistema, consulta [[#Compatibilidad|Compatibilidad]].

Algunas funcionalidades necesitan otras: <code>DynamicPoses</code> requiere <code>GraphicsChange</code>; <code>PalettesEffects</code> requiere <code>PalettesChange</code>; <code>PlayerFeatures</code> necesita ambas opciones de cambios gráficos y de paletas; y <code>YoshiFeatures</code> requiere <code>PlayerFeatures</code>.

== Quick Start ==

'''Guía rápida de instalación:''' [[es/Dynamic_Xtreme_Quick_Start|Quick Start]]

== Herramientas y Soporte ==

Pendiente

== Archivos y formatos ==

'''Artículo relacionado:''' [[es/Dynamic_Xtreme_files_and_formats|Archivos y Formatos de Dynamic Xtreme]]

== Guía de creación de sprites dinámicos ==

Para aprender a preparar, programar, cargar y dibujar un sprite dinámico, consulta la [[es/Dynamic_Xtreme_sprite_creation_guide|guía de creación de sprites dinámicos con Dynamic Xtreme]].

== Dynamic Xtreme con UberASM ==

La [[es/Dynamic_Xtreme_UberASM_guide|guía de Dynamic Xtreme con UberASM]] muestra cómo reservar paletas, configurar el espacio para sprites dinámicos y el límite de datos por frame, crear animaciones, cambiar gráficos del jugador y aplicar efectos de paleta.

== API ==

La [[es/Dynamic_Xtreme_ASM_API|referencia de la API ASM]] explica cómo utilizar las variables, los defines, las rutinas y las macros de Dynamic Xtreme. Incluye los datos que necesita cada llamada, sus resultados y ejemplos de uso para trabajar con poses, dibujo, paletas, efectos de color y transferencias de gráficos, además de las macros de multiplicación y división.

== Funcionamiento interno del sistema ==

El artículo sobre el [[es/Dynamic_Xtreme_internal_workings|funcionamiento interno de Dynamic Xtreme]] explica cómo se organizan NMI y los game modes, las cargas de gráficos y paletas, el dibujo de poses, las optimizaciones, la caché de poses dinámicas y los efectos de paleta.

== Compatibilidad ==

En general, las funcionalidades que no muestran warnings en el instalador no suelen presentar problemas de incompatibilidad con otros recursos. Estas son:

* <code>GraphicsChange</code>
* <code>PalettesChange</code>
* <code>DynamicPoses</code>
* <code>DrawingSystem</code>
* <code>PalettesEffects</code>
* <code>Free7E2000</code>
* <code>ControllerOptimization</code>
* <code>FixedColorOptimization</code>

Esto no garantiza que cualquier combinación de recursos funcione: dos códigos todavía pueden utilizar la misma RAM, el mismo espacio de VRAM o modificar la misma rutina del juego. Además, <code>YoshiFeatures</code> necesita <code>PlayerFeatures</code>, por lo que también debes considerar las restricciones de esta última.

=== Funcionalidades con restricciones de compatibilidad ===

{| class="wikitable"
! Funcionalidad opcional !! Posibles conflictos y qué hacer
|-
| <code>PlayerFeatures</code> || Puede entrar en conflicto con '''LX5's Powerups''', '''Player 8x8 tiles DMAer''', '''Player 32x32''' y otros sistemas que reemplazan la carga de gráficos o paletas del jugador. '''Player Revolution''' sí es compatible. Si tu sistema de jugador necesita esas rutinas originales, deja esta opción deshabilitada; también tendrás que deshabilitar <code>YoshiFeatures</code>.
|-
| <code>YoshiFeatures</code> || Depende de <code>PlayerFeatures</code> y hereda sus restricciones de compatibilidad, aunque no muestre un warning propio. Si otro recurso es incompatible con <code>PlayerFeatures</code>, no puedes evitar ese conflicto habilitando únicamente <code>YoshiFeatures</code>: debes dejar ambas deshabilitadas.
|-
| <code>StatusBarOptimization</code> || No es compatible con recursos que modifican, reemplazan o eliminan la barra de estado original, como '''LX5's DKC Style Status Bar''', '''Minimalistic Status Bar''' y '''Nuke Status Bar'''. Si utilizas uno de ellos, deja esta optimización deshabilitada.
|-
| <code>KevinLMVRAMOptimization</code> || Integra el parche de optimización de VRAM de Lunar Magic de Kevin: utiliza esta versión en lugar del parche original por separado. Su warning también indica que '''no debe desinstalarse después de instalarla''', porque hacerlo puede romper el funcionamiento de la ROM. Si necesitas revertirla, restaura una copia de seguridad anterior a su instalación.
|}

Estas funcionalidades son opcionales: puedes dejar deshabilitada la que entra en conflicto y seguir utilizando los demás sistemas de Dynamic Xtreme, respetando sus dependencias. Deshabilitar una opción no deshace los cambios de otro parche ni elimina la restricción de desinstalación de <code>KevinLMVRAMOptimization</code>.

=== Espacios de RAM utilizados ===

Las direcciones principales se configuran en <code>ASM/DXDefines.asm</code>, dentro de la carpeta de Dynamic Xtreme. En el repositorio, ese archivo corresponde a <code>DynamicXtremeLibrary/ASM/DXDefines.asm</code>.

El espacio utilizado depende de las funcionalidades habilitadas y de si la ROM utiliza SA-1. Los siguientes rangos incluyen el primer y el último byte y están calculados con '''todas las funcionalidades que reservan RAM habilitadas''', <code>!VRAMTransferSize = 64</code> y <code>!CGRAMTransferSize = 64</code>:

{| class="wikitable"
! Configuración !! Bloque <code>!Variables</code> !! Tamaño !! Bloque <code>!Variables2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2000–$7E2500</code> || <code>$0501</code>: 1281 bytes || <code>$7E2800–$7E3608</code> || <code>$0E09</code>: 3593 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB440–$7FB940</code> || <code>$0501</code>: 1281 bytes || <code>$7F9C80–$7FAA88</code> || <code>$0E09</code>: 3593 bytes
|-
| SA-1 || <code>$40C000–$40C47E</code> || <code>$047F</code>: 1151 bytes || <code>$418AFF–$419907</code> || <code>$0E09</code>: 3593 bytes
|}

Los dos bloques internos suman '''4874 bytes en LoROM''' y '''4744 bytes en SA-1'''. La diferencia se debe a los 130 bytes del sistema de dibujo que solo se reservan en LoROM. No se ocupa automáticamente el espacio que queda entre los bloques.

Al deshabilitar una funcionalidad se eliminan sus reservas condicionales y cambian las direcciones posteriores. Aumentar <code>!VRAMTransferSize</code> o <code>!CGRAMTransferSize</code> también aumenta el tamaño de sus tablas.

==== Tablas utilizadas por los sprites ====

<code>DX_FreeRams</code> y <code>DX_FreeRams2</code> '''no son espacios disponibles para escribir variables propias''': a partir de esas posiciones se ubican las tablas de sprites de <code>DynamicXSpritesTables.asm</code> y <code>MoreSpriteMiscs.asm</code>. También debes reservarlas si utilizas esos recursos.

Con la misma configuración de la tabla anterior, sus rangos son:

{| class="wikitable"
! Configuración !! Tablas desde <code>DX_FreeRams</code> !! Tamaño !! Tablas desde <code>DX_FreeRams2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2501–$7E26EC</code> || 492 bytes || <code>$7E3609–$7E3824</code> || 540 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB941–$7FBB2C</code> || 492 bytes || <code>$7FAC82–$7FAE9D</code> || 540 bytes
|-
| SA-1 || <code>$40C47F–$40C6D8</code> || 602 bytes || <code>$419908–$419BCD</code> || 710 bytes
|}

Incluyendo estas tablas, el espacio descrito suma '''5906 bytes en LoROM''' y '''6056 bytes en SA-1'''. Las tablas se calculan para 12 sprites normales en LoROM y 22 en SA-1, además de los slots de cluster, extended y smoke correspondientes.

Normalmente, <code>DX_FreeRams2</code> comienza justo después del segundo bloque interno. En LoROM sin <code>Free7E2000</code> se coloca por separado mediante <code>!Variables3 = $7FAC82</code>; por eso sus tablas no empiezan inmediatamente después de <code>!Variables2</code>.

Dynamic Xtreme también utiliza los espejos existentes del color fijo y de la paleta: <code>$7E0701</code> (2 bytes) y <code>$7E0703</code> (512 bytes) en LoROM. En SA-1 sus direcciones declaradas son <code>$406701</code> y <code>$006703</code>. No son reservas adicionales dentro de los bloques anteriores ni direcciones libres para tus códigos.

==== Reubicar la RAM si hay un conflicto ====

'''Advertencia:''' para reubicar estas variables debes saber qué dirección elegir y considerar el tamaño completo del espacio de memoria que utiliza el sistema. No basta con que una dirección esté libre: debe haber espacio suficiente y las rutinas deben poder acceder a él. Si no tienes conocimientos sobre esto, consulta con alguien que los tenga antes de modificar las direcciones.

Si otro recurso utiliza alguno de estos espacios, puedes modificar '''<code>ASM/DXDefines.asm</code>''' para hacer que Dynamic Xtreme utilice otras zonas disponibles de tu romhack.

* Cambia <code>!Variables</code> y <code>!Variables2</code> en la configuración correspondiente a tu ROM: LoROM con <code>Free7E2000</code>, LoROM sin esa opción o SA-1.
* En LoROM sin <code>Free7E2000</code>, revisa también <code>!Variables3</code>, que determina dónde empiezan las tablas de <code>DX_FreeRams2</code>.
* Reserva espacio suficiente para el bloque completo y las tablas de sprites que le siguen. No basta con que la primera dirección esté libre.
* Respeta el mapa de memoria y los bancos que necesitan las rutinas. No cualquier dirección libre sirve para cualquier acceso.
* Después de cambiar las direcciones, reinstala Dynamic Xtreme y vuelve a insertar PIXI, UberASM y los demás recursos que utilicen sus defines.

Con <code>Free7E2000</code>, Dynamic Xtreme aprovecha el área de RAM que recupera al reubicar los gráficos originales; no la compartas con otros recursos sin comprobar qué parte utiliza. Sin esa opción, las direcciones alternativas pueden coincidir con las de otros recursos habituales. SA-1 utiliza sus propias direcciones y desactiva <code>Free7E2000</code>.

Modifica el archivo de la carpeta '''ASM''', no las copias generadas en <code>ExtraDefines</code> o <code>Patch/ExtraDefines</code>: esas copias se regeneran durante la instalación.

== Recursos hechos con Dynamic Xtreme ==

La mayoría de los recursos desarrollados para Dynamic Xtreme no suelen publicarse en sitios tradicionales como SMW Central debido a que muchos de ellos dependen directamente del framework y sus sistemas avanzados.

En su lugar, los recursos, ejemplos, sistemas y proyectos relacionados con Dynamic Xtreme se encuentran recopilados principalmente en:

https://snestorage.dev

Allí es posible encontrar sprites, sistemas de jugador, efectos gráficos, ejemplos técnicos y otros recursos diseñados específicamente para trabajar con Dynamic Xtreme.

== Conclusión ==

Dynamic Xtreme es un proyecto orientado a modernizar y simplificar el uso de sistemas dinámicos en Super Mario World, ofreciendo herramientas más flexibles, potentes y fáciles de utilizar sin perder compatibilidad ni control avanzado.

El proyecto continúa evolucionando constantemente con nuevas optimizaciones, formatos y herramientas orientadas tanto a usuarios avanzados como a personas que recién comienzan a trabajar con gráficos dinámicos en SNES.

La intención principal de Dynamic Xtreme es permitir la creación de recursos y sistemas cada vez más complejos, manteniendo al mismo tiempo un workflow más limpio, mantenible y accesible para la comunidad.

Dynamic Xtreme internal workings

2026-10-25T22:13:18Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_internal_workings}}

This article explains how Dynamic Xtreme works, from preparing resources during installation to loading and drawing a pose during gameplay.

== What installation prepares ==

Before a sprite can use its graphics or palette, Dynamic Xtreme must store them in the ROM and prepare the information needed to find them. The same applies to any other dynamic resource you add.

The tool reads DynamicInfo, DrawInfo, and PaletteEffect files. Each provides a different part: which resources to load, how to draw poses, and which color changes can be applied.

This generates defines in <code>DXDefines.asm</code> that make it easy to use the resources and call the required routines.

=== DynamicInfo: resources and upload data ===

A DynamicInfo brings together the pose graphics, palettes, and general resources needed by a sprite or other code. For dynamic pose graphics, the tool arranges the data in the tile layout expected by the system.

Several properties of each pose are stored in separate tables. All tables use the same order: a pose's entry in one table corresponds to the same pose in the others. In the table below, '''N''' is the number of installed dynamic poses.

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents and purpose
|-
| <code>PoseSize</code> || 2 × N || 2 || Amount of data used by each pose, in bytes. Used to check whether its upload fits within the frame's budget.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Number of 16×16 blocks to allocate in VRAM for the pose. This does not always match the exact byte count copied, since an incomplete tile can still require a block of space.
|-
| <code>PoseResource</code> || 3 × N || 3 || ROM address of each pose's graphics, including the bank, so upload code can locate the full source address.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; two values per pose || Two sizes per pose, corresponding to the two sections its graphics may be split into. The upload routine uses them to place the data correctly in VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || VRAM offset from the start of the first section to the start of the second. Places the second section correctly even if the first ends with an incomplete row.
|}

These tables describe every installed pose, not just those on screen. The cache separately tracks which poses are loaded and where they are stored.

For example, when a requested pose is not yet in VRAM, the system checks how many bytes it needs to upload, finds space for its blocks, then uses its source address and section data to prepare the upload.

==== Palette tables ====

Palettes declared in DynamicInfo files are collected in <code>PaletteTable</code>. If '''P''' is the number of entries across the DynamicInfo palette lists:

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID of each palette.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || ROM address of its colors.
|}

P counts list entries, not just unique palettes: a shared palette may appear in more than one DynamicInfo.

Both lists follow the DynamicInfo palette order. Each DynamicInfo's offset define identifies where its list starts. Selecting a version adds that index to the offset to find both the ID and address of the chosen colors.

The ID identifies a palette so it can be shared; the address allows its colors to be loaded. Neither is the destination palette number: the same installed palette may be assigned to palette 9 or C, for example.

==== General resources and defines ====

Files declared in <code>Resources</code> are stored in ROM. Their address and byte count are available through defines generated in <code>DXDefines.asm</code>. For example, <code>my_resource.bin</code> generates:

* <code>!ResourceMyResource</code>: resource address in ROM.
* <code>!ResourceMyResourceSize</code>: resource byte count.
* <code>!ResourceIDMyResource</code>: resource ID.

Names are normalized to PascalCase: spaces, hyphens, and underscores are removed, and each word starts with a capital letter.

=== DrawInfo: drawing data and routines ===

The DrawInfo describes how a pose is built: its tiles, each tile's position and size, and how the pose changes when flipped.

During installation, Dynamic Xtreme generates drawing routines optimized for the parameters used by the tiles. For example, it considers whether tiles need X and Y offsets, share a size or common properties, and require flipping.

The resulting routine only handles options that the drawing needs. Several poses can share a routine when they need the same handling; this does not mean they also share graphics or IDs.

These tables connect a pose to its drawing data. '''D''' is the number of drawing poses, and '''R''' is the number of generated routines:

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents and purpose
|-
| <code>TableOffset</code> || 2 × D || 2 || Starting offset of the pose's data in its drawing routine's tables. Locates its tiles and offsets without scanning earlier poses.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || Number of tiles in the pose minus one. A four-tile pose stores 3; the routine uses this to loop through its tiles.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Drawing routine used by each pose. Poses with compatible requirements can use the same routine ID.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 per routine || Drawing routine addresses. The routine ID selects the code to run.
|}

Each routine also has the tables its poses need. Here, '''T''' is the number of entries in each of the routine's tables:

{| class="wikitable"
! Data !! Total bytes !! Bytes per value !! Description
|-
| <code>Tiles</code> || T, if generated || 1 || Tile numbers making up the pose.
|-
| <code>Properties</code> || T, if generated || 1 || Each tile's properties, such as flipping and priority relative to the layers.
|-
| <code>XDisplacements</code> and <code>YDisplacements</code> || T per table, if generated || 1 || Each tile's position relative to the pose's origin.
|-
| Flip displacement tables || T per table, if generated || 1 || Positions used when flipping a pose that requires a different layout.
|-
| <code>Sizes</code> || T, if generated || 1 || Each tile's size: 8×8 or 16×16.
|}

Not every routine needs all these tables. If a value is the same for all tiles or can be obtained from a shared value, the tool can generate a routine that uses it directly.

This optimization happens during installation. For example, when all tiles share a size, the routine can use that common value instead of reading a separate size for each tile.

=== PaletteEffect: effect data ===

A PaletteEffect file contains a list of color changes. Installation assigns IDs to them and stores their data in <code>PaletteEffectsTable</code>.

As with pose tables, each effect occupies the same position across the different lists. Effect IDs start at 1; ID 0 means no global effect. In the table, '''E''' is the number of installed effects; together, the tables occupy '''2 + 7 × E bytes'''.

{| class="wikitable"
! Table section !! Total bytes !! Bytes per value !! Contents
|-
| <code>Length</code> || 2 || 2 || Number of installed effects.
|-
| <code>Types</code> || E || 1 || Each effect's type, such as <code>MixH</code>, <code>MixS</code>, or <code>PalTransitionRGB</code>. Selects the calculation to perform.
|-
| <code>Value1</code>, <code>Value2</code>, and <code>Value3</code> || E per table; 3 × E combined || 1 per table || Channel values used by the effect. For transitions, these three bytes store the target palette address instead.
|-
| <code>Ratio1</code>, <code>Ratio2</code>, and <code>Ratio3</code> || E per table; 3 × E combined || 1 per table || How much of the change to apply to each component. Range: 0–127.
|}

For a transition toward another palette, the tool also prepares that palette. It converts the colors to the RGB or HSL format needed by the transition and stores them in ROM. During gameplay, this target can be used without converting it again on every call.

These transition palettes differ from normal palettes uploaded to CGRAM: they contain three components per color and are used to calculate effects.

=== How code finds installed resources ===

<code>DXDefines.asm</code> provides the IDs, addresses, sizes, and offsets resources need. For example, <code>!DynamicPoseIDMySpriteIdle</code> identifies a pose, and <code>!PaletteEffectIDMyEffect0</code> identifies a file's first effect.

Names are normalized to PascalCase: separators such as spaces, hyphens, and underscores are removed, and each word starts with a capital letter. For example, <code>my_sprite</code> becomes <code>MySprite</code>.

Installation also generates <code>BufferTable</code>, which stores the addresses of the blocks containing inserted resources. Each address occupies 3 bytes, followed by a final <code>$FFFFFF</code> value occupying another 3 bytes. For B blocks, the table occupies <code>3 × (B + 1)</code> bytes. The tool uses this information to find the previous installation's data when reinstalling.

Reinstallation may change IDs and addresses. Reinsert any sprites, blocks, and UberASM code that use the generated defines afterward.

== Work performed each frame ==

The main game logic runs the player, sprites, and other code for the current game mode. Code using Dynamic Xtreme requests poses and palettes, prepares local effects, and calls drawing routines. Accepted uploads are added to the transfer lists for NMI.

Once that logic finishes, Dynamic Xtreme's game mode code performs the tasks enabled by the configuration: preparing VRAM updates for Kevin's optimization, maintaining palette state, and calculating pending global effects.

During NMI, Dynamic Xtreme then performs these tasks in order, according to the enabled features:

# Resets <code>DX_Dynamic_CurrentDataSend</code> to 0.
# Increments <code>DX_Timer</code>.
# Increments <code>DX_SyncTimer</code> if the action is not frozen and the game is not paused.
# Performs graphics transfers to VRAM.
# Performs color transfers to CGRAM.
# Updates color 0,0 if the effect system has a pending result.

The following sections therefore follow this order: '''main logic → tasks at the end of the game mode → NMI transfers'''.

=== Main logic ===

Each resource decides what it needs. A sprite may change pose, an animation may request new graphics, or UberASM code may upload a palette or select an effect.

If the requested pose is already loaded, Dynamic Xtreme updates its last-use time to protect it from replacement without uploading its graphics again. Otherwise, it checks the frame's data budget and finds available VRAM space before preparing the upload.

Drawing is also prepared here: routines write the positions, tiles, and properties of the pieces to display into the OAM buffers.

A request can fail, for example because its data would exceed the remaining budget. The requesting code must check the result and decide whether to keep the previous state or retry later. A rejected upload is not automatically saved for another frame.

=== Game mode tasks ===

This stage performs the following tasks, according to the enabled features.

'''Before game logic runs:'''

# If <code>ControllerOptimization</code> is enabled, the controller routine runs here instead of during NMI.
# Checks whether Dynamic Xtreme should run in the current game mode. If not, its variables are reset. This happens every frame spent in a disallowed mode.

The normal game logic then runs, including sprites and code requesting uploads or palette changes.

'''After that logic finishes:'''

# If Kevin's VRAM optimization is enabled, Lunar Magic's update destinations are adjusted before the transfers take place.
# Palette update flags are cleared to 0, and protection timers greater than 0 are decremented. This is skipped while paused and in disallowed modes.
# Applies global effects to palettes that need an update and prepares their color transfers. This is also skipped if the previous check prevents further processing.

VRAM and CGRAM transfers happen later, during NMI. This stage prepares what will be copied.

=== Allowed game modes ===

Dynamic Xtreme uses two game mode checks:

* '''General system:''' <code>Routines_AllowedGameMode</code>, exposed as <code>!AllowedGameMode</code>. Determines whether the system is reset, its NMI runs, and palette tasks are performed. Palette assignment macros also use this check when processing an upload from a DynamicInfo.
* '''Sprite routines:''' <code>DXAllowedGameMode</code> uses a separate table. <code>!Upload</code> and its general macros use a table with the same values to decide whether to process a new request.

Enabling the general system therefore does not mean every sprite function accepts new uploads in that mode. This table shows the current checks; IDs are hexadecimal:

{| class="wikitable"
! Game mode !! SMW screen or stage !! General system !! DXAllowedGameMode / new Upload requests
|-
| <code>$06</code> || Title screen spotlight opening. || Yes || No
|-
| <code>$07</code> || Title screen. || Yes || Yes
|-
| <code>$08</code> || File select. || Yes || No
|-
| <code>$09</code> || File erase. || Yes || No
|-
| <code>$0A</code> || One- or two-player selection. || Yes || No
|-
| <code>$0C</code> || Overworld loading. || Yes || No
|-
| <code>$0D</code> || Overworld fade-in. || Yes || No
|-
| <code>$0E</code> || Overworld. || Yes || Yes
|-
| <code>$12</code> || Level preparation. || Yes || No
|-
| <code>$13</code> || Level fade-in. || Yes || No
|-
| <code>$14</code> || In-level gameplay. || Yes || Yes
|-
| <code>$15</code> || Fade-out to Game Over / Time Up. || Yes || No
|-
| <code>$1B</code> || Castle cutscene or credits. || No || Yes
|-
| <code>$1C</code> || Fade-out to Yoshi's House in the credits. || Yes || No
|-
| <code>$1D</code> || Loading Yoshi's House in the credits. || Yes || No
|-
| <code>$1E</code> || Yoshi's House fade-in during the credits. || Yes || No
|-
| <code>$1F</code> || Yoshi's House in the credits. || Yes || Yes
|-
| <code>$24</code> || Enemy roll fade-in. || Yes || No
|-
| <code>$25</code> || Credits enemy roll. || Yes || Yes
|-
| <code>$29</code> || The End screen. || No || Yes
|-
| Other values from <code>$00</code> to <code>$2F</code>. || — || No || No
|}

Stage names follow the [https://github.com/IsoFrieze/SMWDisX/blob/master/bank_00.asm SMW game modes documented in SMWDisX]; permissions come from Dynamic Xtreme's tables.

When <code>Upload</code> does not allow a new request, it checks whether the resource has a previous pose. If so, it updates that pose's last-use time and returns carry set; otherwise, it returns carry clear. It does not request another pose on this path.

Modes <code>$1B</code> and <code>$29</code> show why the columns must be read separately: passing the sprite check does not enable the general system's NMI or prevent the game mode code from resetting its variables. The sprite column alone does not guarantee full operation in those modes.

=== Transfers during NMI ===

NMI is an interrupt the SNES can generate at the start of VBlank, after drawing the visible part of the screen. The game uses this interval to update graphics, colors, and other video data.

'''The CPU runs both the game logic and the NMI routine.''' During game logic, it moves sprites and prepares upload requests. At the start of VBlank, an NMI can temporarily interrupt that logic to handle video updates. When the NMI routine finishes, the CPU resumes the interrupted code.

This is the usual sequence within a frame:

{| class="wikitable"
! Stage !! What the CPU does !! What happens to graphics
|-
| Game logic
| Moves sprites, selects poses, calculates effects, and prepares drawing.
| Accepted requests are stored in the transfer lists.
|-
| VBlank, during NMI
| Runs the NMI routine and sets up DMA transfers.
| Graphics are copied to VRAM, colors to CGRAM, and OAM data to OAM memory.
|-
| After NMI
| Resumes the interrupted code.
| The updated data is used to draw the next image.
|}

This table shows the usual sequence; during slowdown, SMW may run a shortened NMI, as explained in the <code>DX_Timer</code> section.

In allowed modes, Dynamic Xtreme performs these tasks in order, according to the enabled features:

# Resets <code>DX_Dynamic_CurrentDataSend</code> to 0 to count requests from the next logic cycle. Transfers already prepared remain in their lists.
# Increments <code>DX_Timer</code>.
# Checks <code>$9D</code> and <code>$13D4|!addr</code>. If both are 0, increments <code>DX_SyncTimer</code>.
# Performs pending VRAM transfers if <code>GraphicsChange</code> is enabled.
# Performs pending CGRAM transfers if <code>PalettesChange</code> is enabled.
# If <code>PalettesEffects</code> is enabled, updates color 0,0 when a result is pending.

The copies use DMA. NMI reads each request from the lists, sets the source address, byte count, and destination, then starts the transfer.

VBlank time is limited, and SMW also needs it for its own screen updates. To limit data sent in one frame and prevent flickering, Dynamic Xtreme uses <code>DX_Dynamic_CurrentDataSend</code> to count requested bytes and <code>DX_Dynamic_MaxDataPerFrame</code> to set the limit. Before accepting a normal upload, it checks whether the additional bytes would exceed that limit.

==== Transfer lists ====

Each request stores the source address and bank, byte count, and VRAM or CGRAM destination.

NMI processes the lists from the last entry to the first, then empties them. This does not erase the uploaded graphics or colors: they stay at their destinations until other code changes them.

The VRAM list uses 0 when empty. The CGRAM list uses <code>$FF</code> because it stores the last entry's index rather than the entry count directly.

Code writing to the same destination must coordinate its uploads. Request order does not replace deciding which resource may use each region.

Resources are normally read from ROM. If a resource is in a RAM buffer, you must keep its contents unchanged until NMI performs the transfer. For example, a palette prepared in RAM must not be modified or its buffer reused before the copy. The list stores the address, not a copy of the data; Dynamic Xtreme does not protect the buffer from changes made by other code.

==== Data budget ====

Transfer macros such as <code>%TransferToVRAM()</code> and <code>%TransferToCGRAM()</code> check the requested byte count in <code>DX_Dynamic_CurrentDataSend</code>. If the new upload would exceed <code>DX_Dynamic_MaxDataPerFrame</code>, it is rejected. Accepted uploads add their bytes to the counter.

The default limit is <code>$0800</code>, or 2048 bytes. It helps prevent flickering caused by sending too much data in a frame. It limits data volume, rather than measuring the exact time each transfer takes.

<code>DX_Dynamic_CurrentDataSend</code> tracks the requested byte count. The check <code>CurrentDataSend + resource bytes > MaxDataPerFrame</code> rejects a normal upload that would exceed the budget, limiting the data transferred during VBlank.

Dynamic pose requests return the same failure result for insufficient budget and insufficient usable VRAM space. The call does not identify which condition prevented the upload. Failure does not mean VBlank was overloaded either: when the budget causes a rejection, the upload is rejected specifically to prevent that overload.

Variants such as <code>%ForcedTransferToVRAM()</code> and <code>%ForcedTransferToCGRAM()</code> accept uploads without checking the limit. Their bytes still count toward <code>DX_Dynamic_CurrentDataSend</code>, leaving less room for later normal uploads. They are used for priority uploads, such as the player's graphics; they do not prevent flickering if too much data is requested.

See [[Dynamic_Xtreme_ASM_API#PPU|PPU in the ASM API]] for the difference between byte budget and list capacity, transfer restrictions, and the checks your code must perform.

==== The two timers ====

'''DX_Timer: protecting requests'''

<code>DX_Timer</code> advances when Dynamic Xtreme's NMI code runs. Besides measuring how long a pose has gone unused, it prevents a resource from repeating requests before its previous ones have been processed.

A logic cycle does not always correspond to a full NMI execution. During slowdown, SMW may run a shortened NMI, allowing two logic cycles to occur without Dynamic Xtreme's transfer lists being processed between them.

Without protection, a resource could add its uploads to those lists again. Duplicate requests would take more space and could cause flickering.

To prevent this, sprite pose upload routines compare <code>DX_Timer</code> with a two-byte value stored by the sprite, usually called <code>SafeFrame</code>. The sprite aliases use <code>!SafeFrameLowByte,x</code> and <code>!SafeFrameHighByte,x</code>.

The process is:

# '''Compare the timers.''' If <code>SafeFrame</code> equals <code>DX_Timer</code>, that sprite has already processed its pose upload at this timer value. The routine skips a new request.
# '''Record the attempt before processing it.''' If the values differ, it copies <code>DX_Timer</code> to <code>SafeFrame</code>, then checks whether it can reuse the pose or must request another.
# '''Check the result.''' A new pose request can succeed or fail. Even if it fails, the value saved in <code>SafeFrame</code> is not undone.

<code>SafeFrame</code> therefore records '''when the last attempt was processed''', not when a pose was successfully loaded. If an upload fails, calling the routine again with the same <code>DX_Timer</code> does not allow another attempt, even if the desired pose or available space has changed.

In <code>!Upload</code> and <code>!UploadWithoutPoseOffset</code>, rejected requests and calls skipped by this protection use the same fallback:

* If <code>!LastPoseHashIndex,x</code> is not <code>$FF</code>, they update that pose's last-use time to protect it from replacement and return carry set. The sprite can keep drawing the last available pose.
* If it is <code>$FF</code>, no fallback pose exists and they return carry clear.

For example, this can happen during slowdown:

# <code>DX_Timer = $0030</code>. The sprite saves <code>$0030</code> in its <code>SafeFrame</code> and tries to obtain a new pose. No data budget remains, so the request fails; it keeps the previous pose if one exists.
# SMW runs another logic cycle without processing Dynamic Xtreme's NMI. The timer is still <code>$0030</code>. The same sprite's next call detects the match and does not repeat the request.
# When Dynamic Xtreme's NMI runs, <code>DX_Timer</code> advances to <code>$0031</code>. On the next call, the timers no longer match and the sprite can retry. A rejected request does not retry itself: the sprite code must call the routine again.

Sprite pose upload aliases enable this protection. In [[Dynamic_Xtreme_ASM_API#GeneralUpload|GeneralUpload]] and [[Dynamic_Xtreme_ASM_API#Upload_(general_macro)|Upload (general macro)]], <code>safeCheck</code> controls it; <code>checkLast</code> separately controls fallback to the previous pose. [[Dynamic_Xtreme_ASM_API#TakeDynamicRequest|TakeDynamicRequest]] and [[Dynamic_Xtreme_ASM_API#PPU|PPU transfer macros]] do not perform this <code>SafeFrame</code> check for you.

<code>DX_Timer</code> continues advancing while paused whenever this part of NMI runs.

'''DX_SyncTimer: synchronized animations'''

The main purpose of <code>DX_SyncTimer</code> is to give sprites a shared animation clock. For example, sprites using the same poses can use it to select a pose every four frames.

They then change together and request the same pose. The first request may need to upload it; later requests reuse it without scheduling another graphics upload. This saves DMA transfers and data per frame.

With independent timers, sprites could use different poses from the same animation at once, requiring more uploads and VRAM space.

<code>DX_SyncTimer</code> stops while paused or while the action is frozen, so synchronized animations stop too.

== Graphics uploads: GraphicsChange ==

<code>GraphicsChange</code> stores a list of upload requests in RAM. During NMI, those requests are processed and their data is copied to VRAM.

=== List variables ===

Here, '''V''' is <code>!VRAMTransferSize</code>, which defaults to 64. Each of the four request tables allocates V bytes; with 2-byte entries, that allows 32 requests. Together with the counter, they occupy <code>1 + 4 × V</code> bytes: 257 by default.

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Number of pending requests. 0 means the list is empty.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 by default || 2 || Each request's source address, excluding the bank.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 by default || 2 allocated; 1-byte bank || Source bank.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 by default || 2 || Number of bytes to copy.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 by default || 2 || VRAM destination address.
|}

Tables use the same order: the first entry of each table belongs to the first request, the second to the second request, and so on. Each entry occupies 2 bytes, so offsets advance through <code>$00</code>, <code>$02</code>, <code>$04</code>, and so on.

These names represent RAM addresses calculated in <code>DXDefines.asm</code>. Addresses can change with the configuration and enabled features.

=== Adding a request ===

<code>%TransferToVRAM()</code> performs these steps:

# Calculates the total byte count if the new upload is added to <code>DX_Dynamic_CurrentDataSend</code>.
# Compares it with <code>DX_Dynamic_MaxDataPerFrame</code>. If it exceeds the limit, returns carry clear without adding the request.
# Uses <code>DX_PPU_VRAM_Transfer_Length</code> to find the next entry and increments that counter.
# Stores the source, bank, byte count, and destination in the tables.
# Updates <code>DX_Dynamic_CurrentDataSend</code> with the upload's byte count and returns carry set.

<code>%ForcedTransferToVRAM()</code> stores the same information without checking the byte limit. <code>FromAddr</code> and <code>Resource</code> variants make it easier to get the source from a full address or resource defines.

Adding a request does not copy graphics immediately: it prepares the information for NMI.

=== Processing requests during NMI ===

The <code>VRAMDMA</code> routine:

# Reads <code>DX_PPU_VRAM_Transfer_Length</code>. If it is 0, returns because there are no requests.
# Calculates the last entry's offset: <code>(Length - 1) × 2</code>.
# Reads its source, bank, and byte count into the DMA registers.
# Writes the VRAM destination to <code>$2116-$2117</code> and starts the transfer through <code>$420B</code>.
# Moves back 2 bytes to process the previous request, repeating until the first is complete.
# Writes 0 to <code>DX_PPU_VRAM_Transfer_Length</code> to mark the list as empty.

'''The list runs from last to first.''' There is no need to clear every stored value afterward: with the length at 0, the next request reuses the first entry.

=== Animations with a fixed destination ===

Animation code must:

# Select the image for the current animation step.
# Calculate its source address.
# Request a transfer to the animation's VRAM destination.
# Check carry. If the upload is rejected, keep the previous image and retry.

The destination can stay the same. Only the image copied there changes; the transfer list does not decide when the animation advances.

See [[Dynamic_Xtreme_UberASM_guide#Creating_graphics_animations|Creating graphics animations in the UberASM guide]] for complete code.

=== Loading a dynamic pose ===

Pose loading uses the cache to avoid uploading graphics that are already available:

# Looks for the ID in the hash table.
# If already registered, updates its last-use time without adding another upload.
# Otherwise, checks the byte count and finds suitable space in the VRAM map.
# Selects poses that can be replaced, considering their time since last use and the new pose's space requirements.
# Updates the cache tables and map.
# <code>DynamicRoutine</code> splits the pose's data into the required transfers.
# NMI performs those transfers.

[[#Dynamic_sprites:_DynamicPoses|Dynamic sprites: DynamicPoses]] covers each step, including hash lookup, the map, replacement policy, and splitting uploads into rows.

== Palette uploads and assignment: PalettesChange ==

The system distinguishes two values:

* '''Palette ID:''' identifies colors stored in ROM.
* '''Destination color:''' specifies the starting color in CGRAM for the uploaded colors. For example, <code>$91</code> starts at color 1 of palette 9.

Automatic assignment lets sprites share colors without requiring a fixed destination for each sprite.

=== CGRAM upload list ===

Here, '''C''' is <code>!CGRAMTransferSize</code>, which defaults to 64. The tables and counter allocate <code>1 + 7 × C</code> bytes, or 449 by default. Although <code>SourceBNK</code> allocates 2 × C bytes, the code uses one bank byte per request.

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Last pending request's index. <code>$FF</code> means the list is empty; 0 means one request.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 by default || 2 || Source address, excluding the bank.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 allocated by default || 1 used per request || Source bank.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 by default || 2 || Number of bytes to copy. Each color occupies 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 by default || 1 || First destination color in CGRAM.
|}

During NMI, <code>CGRAMDMA</code>:

# Starts at the last pending request.
# Configures DMA with that request's source and byte count.
# Selects the first color through <code>$2121</code> and performs the copy.
# Continues with earlier requests.
# Writes <code>$FF</code> to <code>DX_PPU_CGRAM_Transfer_Length</code> when finished.

<code>TransferPalette</code> macros also update the color copies and effect state:

* '''Without the global effect:''' request the upload and update SMW's buffers, preventing the game from reusing old colors during the goal victory animation.
* '''With the global effect:''' store the original colors and prepare the state needed to apply the effect before sending them to CGRAM.

=== Automatic assignment ===

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Purpose
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || ID assigned to each destination. <code>$FFFF</code> marks a free entry; <code>$FFFE</code> marks one set aside.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protects each destination from automatic replacement while in use.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; one bit per sprite palette || Tracks sprite palettes assigned with the global effect enabled. Sharing an assignment also requires this setting to match.
|}

The search follows this order:

# Reuse an assignment with the same ID and compatible effect setting.
# If none exists, use a free entry.
# If none is free, replace an entry that is not set aside and whose timer is 0.
# If no entry qualifies, report assignment failure.

While using the palette, the resource keeps its timer at 2. Reaching 0 does not erase the colors: the assignment can still be reused if another resource has not replaced it.

=== Manual assignment and version ===

* '''Manual with upload:''' code selects the destination and requests its colors.
* '''Manual without upload:''' code selects the destination and uses the colors already available there.
* '''Version:''' selects an entry in the DynamicInfo palette list. The last processed version lets the system check whether that selection changed.

Resources choosing the same destination with different colors must coordinate their uploads. Keeping a palette protected does not mean uploading its colors again.

== Pose drawing: DrawingSystem ==

Drawing prepares a pose's pieces in OAM: the tiles to display, their positions, and their properties. The graphics data must be in VRAM.

=== Drawing steps ===

# Finds the pose's routine and data through <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code>, and <code>TableOffset</code>.
# Gets the tile count from <code>NumberOfTilesMinus1</code>.
# Calculates each tile's position from the sprite position, displacements, and applicable flips.
# Checks whether the tile is visible and OAM space remains.
# Writes its position, tile number, properties, and size to the OAM buffers.

The tile number depends on the drawing type:

{| class="wikitable"
! Case !! How the tile is selected
|-
| Dynamic pose || Adjusted to the graphics' location in VRAM.
|-
| Static pose || Uses its fixed tile number.
|-
| Pose using a shared tile || Code must set <code>!Tile</code> before drawing.
|}

=== Priority and available space ===

* In '''LoROM''', the system tracks available OAM entries itself.
* In '''SA-1''', it integrates with MaxTile.
* '''Drawing priority''' orders sprite tiles. It is separate from the property that places a tile in front of or behind layers.
* SNES '''per-scanline limits''' still apply. Loading a pose does not guarantee that all its tiles can be displayed.

== Player and Yoshi ==

=== PlayerFeatures ===

The original player has its own routines to select and upload pose pieces. <code>PlayerFeatures</code> integrates that work with Dynamic Xtreme uploads and lets you change the graphics and palette sources.

With the original format, the game still selects the pose pieces. The routine gets their addresses from the configured source and compares them with the previous addresses to upload only those that changed.

These uploads use forced transfers, and their bytes also count toward later normal requests. They retain priority while remaining part of the system's data budget.

The player's palette receives special handling: it combines the game's own colors and selections with the custom source. It is more involved than replacing an ordinary sprite's entire palette.

Support for custom players lets other systems handle their poses and drawing differently. It does not automatically convert any spritesheet to the original player's format.

=== YoshiFeatures ===

Yoshi also uploads graphics in pieces. <code>YoshiFeatures</code> lets you change their source while retaining the layout expected by the routines.

The code calculates which pieces are needed and prepares uploads to the corresponding VRAM destinations. Like the player's uploads, these receive priority handling.

This option requires <code>PlayerFeatures</code> and shares its compatibility restrictions. Enabling Yoshi's features alone does not avoid a conflict with the player system.

== Differences between LoROM and SA-1 ==

The main differences in Dynamic Xtreme between these configurations are the memory used for its variables and the drawing system:

{| class="wikitable"
! Aspect !! LoROM !! SA-1
|-
| Memory for variables
| <code>Free7E2000</code> is commonly used to provide space for Dynamic Xtreme's variables in the recovered RAM. If this option causes compatibility problems, it can be disabled in favor of the alternative configuration, which uses a tighter RAM allocation.
| Does not use <code>Free7E2000</code>. The main variable areas are in BW-RAM, in banks <code>$40</code> and <code>$41</code>.
|-
| Drawing priorities
| Uses Dynamic Xtreme's own system, with two drawing priorities.
| Uses MaxTile, with four drawing priorities for tiles.
|}

LoROM's two priorities cannot preserve every ordering distinction available with SA-1's four priorities. Some resources that draw correctly on SA-1 may therefore appear in a different or incorrect drawing order on LoROM. These priorities order sprite tiles; they are separate from the priority that places tiles in front of or behind layers.

See [[Dynamic_Xtreme#RAM_usage|RAM usage]] for each configuration's memory ranges.

== Memory and optimizations ==

=== Free7E2000 ===

SMW keeps original player, Yoshi, and some animation graphics in RAM. In ROMs without SA-1, this option adapts uploads to read that data from ROM instead.

Dynamic Xtreme uses the recovered RAM for its internal variables. It is not free space for other code to overwrite.

SA-1 uses different addresses and disables this option. See the ranges in [[Dynamic_Xtreme#RAM_usage|RAM usage]].

=== ControllerOptimization ===

This option moves controller processing from NMI to the game mode code. It frees time for screen updates without adding a frame of input delay or changing which buttons the game receives.

=== FixedColorOptimization ===

The console uses the fixed color for color math. To update it, the game prepares its components and sends them to the corresponding register.

This optimization replaces that preparation with a shorter sequence. The color is still sent to the console, with less work required during NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic uses lists called stripe images to update parts of the tilemaps. These contain both the data and destination information.

The integrated version of Kevin's optimization prepares part of the destination adjustment outside NMI, leaving less setup work for transfer time.

This option replaces the standalone original patch. It must not be uninstalled after installation; keep this in mind before enabling it.

=== StatusBarOptimization ===

The original status bar updates specific VRAM regions. This option prepares its transfers more directly, reducing the DMA setup needed during NMI.

It modifies updates to the original status bar rather than adding a new one. As a result, it conflicts with resources that replace, modify, or remove that bar.

== Dynamic sprites: DynamicPoses ==

The system works as a '''pose cache in VRAM'''. Instead of keeping a graphics copy for each sprite, it stores a pose that every resource needing it can reuse.

* A pose is uploaded only once while it remains in the cache.
* Later requests update its last-use time without adding another graphics upload.
* A pose is not erased when a resource stops using it. It stays until its space is needed and it is selected for replacement.
* If replaced and later requested again, it must be uploaded again.

Replacement depends on '''time since last use''', not time since upload, as well as whether the space fits the new pose.

=== Three different values ===

{| class="wikitable"
! Value !! What it identifies
|-
| Pose ID || The installed pose. A 16-bit value used to look up its data in ROM.
|-
| Hash table index || The RAM entry that records the pose. Ranges from 0 to 127.
|-
| VRAM block || ID of one of the 128 16×16 tile positions in sprite VRAM. Numbered left to right and top to bottom, from 0 to 127. A pose occupying several blocks stores its first block's ID.
|}

The hash table index and VRAM block do not need to match. A table entry can record a pose starting at any allowed block.

=== Registered pose tables ===

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Number of registered poses.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Number of registered poses for each hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || Full pose ID in each entry. <code>$FFFF</code> marks a free entry.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Starting VRAM block of each pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || <code>DX_Timer</code> value at the pose's last use.
|}

These tables occupy '''769 bytes''' of RAM. They track poses registered during gameplay, whereas the DynamicInfo-generated tables describe every installed pose.

=== Looking up a pose ===

<code>DynamicPoseHashmap_FindPose</code> uses a 128-entry hash table. The hash selects where to start searching:

<pre>
hash = pose ID AND $007F
</pre>

Different IDs can share a hash. For example, <code>$0005</code> and <code>$0085</code> both produce <code>$05</code>. The hash alone therefore cannot confirm that a pose is loaded; the full ID must also match.

The search follows these steps:

# Saves the requested ID and calculates its hash.
# If <code>DX_Dynamic_Pose_Length</code> is 0, no poses are registered and the search ends.
# Checks <code>DX_Dynamic_Pose_HashSize[hash]</code>. If it is 0, no registered pose has that hash, so the search also ends.
# Starts at the entry whose index matches the hash.
# Reads that entry's ID. If it matches the requested ID, the pose has been found.
# Otherwise, continues to the next entry in the search sequence.

The sequence advances '''15 entries per attempt''', wrapping around after 127:

<pre>
next index = (current index + 15) AND $7F
</pre>

With 128 entries, this step visits every position before repeating one. For hash <code>$05</code>, the sequence starts:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

==== The pose count for each hash ====

Each hash has its own counter in <code>DX_Dynamic_Pose_HashSize</code>. For example, if two registered poses have IDs that produce hash <code>$05</code>, <code>DX_Dynamic_Pose_HashSize+$05</code> contains 2.

This number tells the search '''how many poses have that hash''', not how many positions to visit. The search uses a temporary copy of the counter:

# Starts with the registered pose count for the requested hash.
# Visits positions in the sequence until it finds the requested ID or has checked that many poses with the same hash.
# Each time it finds a pose with the same hash but a different ID, decrements the temporary counter.
# Free positions and poses with other hashes do not decrement it; the search continues.
# If the temporary counter reaches 0 without finding the ID, the requested pose is not registered and the search ends.

The counter in <code>DX_Dynamic_Pose_HashSize</code> does not change during lookup. It changes only when poses are added to or removed from the cache.

For example, suppose the requested ID is <code>$0105</code>, which produces hash <code>$05</code>, and that hash's counter is 2:

{| class="wikitable"
! Visited position !! Stored ID !! ID's hash !! Hash $05 poses still to check
|-
| <code>$05</code> || <code>$0005</code> || <code>$05</code> || 1: same hash, but a different ID.
|-
| <code>$14</code> || <code>$0014</code> || <code>$14</code> || 1: different hash, so the counter is unchanged.
|-
| <code>$23</code> || <code>$0085</code> || <code>$05</code> || 0: both poses with this hash have been checked. <code>$0105</code> is not registered.
|}

Usually, each hash has one or two poses. This allows lookup with few comparisons and a typical cost close to <code>O(1)</code>. It does not mean only one or two positions are always visited: entries with other hashes may lie between them. Many collisions can make the search longer.

'''A free entry does not end the search.''' It may have been emptied by replacing a pose, with another pose of the same hash still farther along the sequence. The counter tells the search when all poses with that hash have been checked, even with gaps between them.

==== When the pose is found ====

<code>TakeDynamicRequest</code>:

# Gets the matching entry's index.
# Writes the current <code>DX_Timer</code> value to that entry's <code>DX_Dynamic_Pose_TimeLastUse</code>.
# Reports request success without scheduling another graphics upload.

All resources requesting that ID therefore use the same pose and keep it protected. They may be normal, cluster, or extended sprites, or any other code using the system.

This also prevents duplicate uploads within one cycle: once the first request is accepted, the pose is registered even though the actual transfer will occur during NMI.

=== When the pose is not registered ===

<code>TakeDynamicRequest</code> proceeds with a new upload:

# Reads <code>PoseSize</code> and calculates <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# If the result exceeds <code>DX_Dynamic_MaxDataPerFrame</code>, returns failure without changing existing poses.
# Reads <code>Pose16x16Blocks</code> to find the required block count.
# Calls <code>VRAMMap_GetBestSlot</code> to find suitable space.
# If no usable space exists, returns failure.
# Removes poses occupying the chosen space from the map and hash table.
# Finds a free hash table entry and registers the new pose.
# Updates the VRAM map and frame data counter.
# Calls <code>DynamicRoutine</code> to add the transfers.

The budget check happens before replacing poses. If the new upload cannot fit in the frame, no space is freed for a request that cannot be fulfilled.

==== Adding and removing hash table entries ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> looks for an entry whose ID is <code>$FFFF</code>, using the same sequence of 15-entry steps.
* <code>DynamicPoseHashmap_Add</code> stores the ID and last-use time, increments <code>DX_Dynamic_Pose_Length</code>, and increments the corresponding hash counter.
* <code>DynamicPoseHashmap_Remove</code> writes <code>$FFFF</code> to the removed ID and decrements both counters.

Removing an entry does not itself erase VRAM pixels. It marks the pose as unavailable in the cache; the new transfers overwrite the chosen space.

=== Representing the VRAM map ===

The map represents '''128 16×16 tile positions in sprite VRAM''', numbered left to right and top to bottom. Each block is one of those positions, not a contiguous 128-byte range.

A 16×16 tile consists of four 8×8 tiles arranged in two rows. The map manages the positions occupied by a pose; <code>DynamicRoutine</code> later handles how its data must be distributed for upload.

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Section's starting position. Bit <code>$80</code> marks it as restricted: dynamic poses cannot use this space.
|-
| <code>DX_Dynamic_Tile_Size</code>, also called <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || If bit <code>$80</code> is set, the remaining bits hold the section's position count minus one. Otherwise, they hold the occupying pose's hash index. Check <code>Offset</code> to determine whether the space is restricted.
|}

These two tables occupy '''256 bytes'''. Together with the pose tables, the manager uses '''1025 bytes''' of RAM, excluding transfer lists and working scratch memory.

=== Map sections ===

A section groups consecutive map positions that are restricted, free, or occupied by one pose. Its information is stored at '''the first and last positions''', allowing traversal to jump to the previous section without checking every position in between.

The following examples show three possible states for a 6-position section from <code>$20</code> to <code>$25</code>. These are alternatives, not three sections occupying the same space at once.

==== Example 1: restricted section ====

{| class="wikitable"
! Table entries !! Value !! Meaning
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> and <code>+$25</code> || <code>$A0</code> || <code>$80</code> marks the restriction; <code>$20</code> identifies the start.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> and <code>+$25</code> || <code>$85</code> || The section has 6 positions: <code>($85 AND $7F) + 1 = 6</code>.
|}

Although the high bit of <code>Size</code> is set, '''this space is not free for dynamic poses''': the restriction bit in <code>Offset</code> excludes it. It is not evaluated as a replaceable pose.

<code>DynamicPoseSpaceConfig</code> uses this section type to exclude parts of SP1–SP4 that dynamic sprites must not use.

==== Example 2: free section ====

{| class="wikitable"
! Table entries !! Value !! Meaning
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> and <code>+$25</code> || <code>$20</code> || Starts at <code>$20</code> and is not restricted.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> and <code>+$25</code> || <code>$85</code> || Bit <code>$80</code> marks a free section's size: <code>$05 + 1 = 6</code> positions.
|}

This section is available. It can hold a pose needing up to 6 positions; placing a 4-position pose leaves the other 2 as a separate free section.

==== Example 3: section occupied by a pose ====

Suppose a 6-block pose is registered at hash entry <code>$07</code> and occupies positions <code>$20</code> through <code>$25</code>:

{| class="wikitable"
! Table entries !! Value !! Meaning
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> and <code>+$25</code> || <code>$20</code> || The section starts at <code>$20</code> and is not restricted.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> and <code>+$25</code> || <code>$07</code> || Bit <code>$80</code> is clear: <code>$07</code> is the pose's hash index, not its block count.
|}

To find the position count and time since last use:

# Read the pose ID at <code>DX_Dynamic_Pose_ID+$0E</code>. The offset is <code>$0E</code> because each ID occupies 2 bytes and <code>$07 × 2 = $0E</code>.
# Use that ID to read <code>Pose16x16Blocks</code>, which contains 6 in this example.
# Read <code>DX_Dynamic_Pose_TimeLastUse+$0E</code> to calculate how long the pose has gone unused.

<code>DX_Dynamic_Pose_Offset+$07</code> stores <code>$20</code>, connecting the registered pose to its VRAM position.

=== Traversal and space search ===

<code>VRAMMap_GetBestSlot</code> starts at 16×16 tile position <code>$7F</code>. To traverse the map:

# Reads <code>DX_Dynamic_Tile_Offset</code> at the current position.
# Gets the section's start with <code>Offset AND $7F</code>.
# Evaluates that section and spaces it can form with adjacent sections.
# Moves to <code>section start - 1</code>, the previous section's last position.
# Repeats until reaching the beginning of the map.

For example, if the last sections start at <code>$70</code>, <code>$60</code>, and <code>$50</code>:

{| class="wikitable"
! Visited position !! Start read from Offset !! Next position
|-
| <code>$7F</code> || <code>$70</code> || <code>$6F</code>
|-
| <code>$6F</code> || <code>$60</code> || <code>$5F</code>
|-
| <code>$5F</code> || <code>$50</code> || <code>$4F</code>
|}

This traverses '''whole sections''', not every tile in between.

==== What the traversal evaluates ====

A candidate space can consist of '''one section or several adjacent sections'''. At each step, the search checks:

* A restricted section cannot be used, and sections cannot be combined across it.
* A pose protected by recent use cannot be part of the space either.
* If the candidate is still too small, an adjacent section can be added to reach the required block count.
* Once the pose fits, the candidate is compared with the best one found: first by its time-since-last-use score, then by the smallest sufficient space.

A section is not chosen merely because it contains the longest-unused pose. The '''whole space''' must fit the new pose. When combining sections, the score depends on the most recently used pose within that space.

The search keeps these temporary values:

{| class="wikitable"
! Working data !! Total bytes !! Bytes per value !! Purpose
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 per field || Start, score, and block count of the current candidate.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 per field || Same fields for the best candidate found.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Block count needed by the new pose.
|}

These names refer to working scratch memory, not additional persistent RAM.

=== Replacement policy: time since last use and enough space ===

The system does not simply choose the first pose uploaded. It uses the time since the pose's '''last use''':

<pre>
time since last use = DX_Timer - pose TimeLastUse
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> gets each region's size and score:

{| class="wikitable"
! Case !! Score and handling
|-
| Free region || <code>$FF</code>. Preferred over occupied regions.
|-
| Occupied region || Time since last use, capped at <code>$FE</code>.
|-
| Unused for 0 or 1 timer increments || Cannot be replaced: the pose is still protected.
|-
| Restricted region || Excluded: dynamic poses cannot use this space.
|}

Protection requires '''at least two increments of <code>DX_Timer</code> without using the pose''' before it can be replaced. Each resource requesting it again updates its last-use time and protects it again.

==== Why the longest-unused pose is not always replaced ====

The new pose needs enough contiguous space. A small space alone is not useful, even if it has gone unused for a long time.

For example, consider a new pose needing 4 blocks:

{| class="wikitable"
! Candidate space !! Time since last use !! Suitable?
|-
| Pose A: 2 blocks, with no usable adjacent space || 20 || No: frees only 2 blocks.
|-
| Pose B: 4 blocks || 8 || Yes: fits the new pose.
|}

Here, B can be replaced while A stays. A has gone unused longer, but its space cannot satisfy the request.

If two or more adjacent regions can be replaced, the system can consider them together. It then:

* Adds their block counts.
* Uses the '''lowest score''' among them: the shortest time since last use.
* Excludes any restricted or protected region from the combined space.

This prevents a recently used pose from being overwritten just because it is next to a long-unused one.

==== Choosing among valid candidates ====

# The candidate must have at least the requested block count.
# The highest score wins: free space or the longest time since last use.
# If scores match, the smaller candidate wins, provided the pose fits.
# If score and size both match, the previously chosen candidate is kept.

Regions are combined during the search when the candidate is still too small. The system does not combine every replaceable region regardless of the requested size.

=== Replacing and splitting the chosen region ===

Once the space is chosen:

# <code>VRAMMap_RemovePosesInSpace</code> traverses its regions and removes poses being replaced from the hash table.
# <code>VRAMMap_RemoveSpace</code> marks the chosen space as one free region by updating its endpoints.
# A free hash entry is found, and the starting block is stored in <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registers the pose.
# <code>VRAMMap_AddPoseInSpace</code> writes the pose's hash index and region start at the first and last blocks.
# Any leftover blocks become another free region.

If a 6-block region holds a 4-block pose, it becomes a 4-block occupied region and a 2-block free region. Dynamic Xtreme has no VRAM defragmentation system: it does not move loaded poses to bring free spaces together.

=== DynamicRoutine: preparing pose transfers ===

At this point, space has been chosen and the pose registered. <code>DynamicRoutine</code> turns that allocation into transfer requests.

It uses these values:

{| class="wikitable"
! Data !! Amount read per pose !! Purpose
|-
| Starting block || 1 byte || Position chosen by the VRAM map.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes from a 256-byte table || Converts one of the 128 blocks to a VRAM offset.
|-
| <code>PoseResource</code> || 3 bytes || Full ROM address of the pose data.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: two 2-byte values || Byte counts of the first and second sections.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || VRAM offset for the second section.
|}

==== Converting the block to a VRAM address ====

A 16×16 block does not convert to a simple linear byte offset. Each block uses 8×8 tiles distributed across VRAM rows.

<code>OffsetToVRAMOffset</code> accounts for that layout. For example:

{| class="wikitable"
! Block !! Offset !! VRAM address
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

These VRAM addresses are measured in 2-byte words, not bytes. The routine adds the <code>$6000</code> base used for sprite graphics.

==== Processing sections and rows ====

# Gets the source from <code>PoseResource</code>.
# Processes the first section's bytes through <code>DynamicRoutineLine</code>.
# If the second section's size is 0, returns.
# Otherwise, advances the source by the first section's byte count.
# Adds <code>PoseSecondLineOffset</code> to the VRAM offset and processes the second section.

<code>DynamicRoutineLine</code> splits each section according to its rows and starting position. For destination V measured in VRAM words, it prepares:

<pre>
First row end = (V + $0100) AND $FF00
Bytes to that end = (first row end - V) × 2
Second part destination = first row end + $0100
Second part bytes in a group = $0200 - first part bytes
</pre>

Sizes are byte counts, while VRAM destinations are word addresses. This is why the calculation multiplies by 2 to find how many bytes fit before the end of a row.

The routine uses three paths:

* <code>.EndLine</code>: adds one final request for the remaining bytes.
* <code>.TwoLinesWithEndLine</code>: adds two requests for the remaining data, each with its own destination and byte count.
* <code>.TwoLines</code>: adds two requests totaling <code>$0200</code> bytes, advances the source and destinations, and repeats for the remaining data.

A direct path precedes the general loop: if the destination starts on a <code>$0100</code>-word boundary and the section contains at least <code>$0200</code> bytes, the routine uses <code>.EndLine</code> to prepare the entire section as one request.

For example, a <code>$0200</code>-byte section starting at <code>$6020</code> is split as follows:

{| class="wikitable"
! Request !! Source !! VRAM destination !! Bytes
|-
| First || Section start || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Second || Section start + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Together, the two requests copy the section's 512 bytes to the destinations calculated from the row layout. They are not two complete copies of the pose.

Each request uses these tables:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Each added request increments <code>DX_PPU_VRAM_Transfer_Length</code>.

The pose's total byte count was already checked and added to <code>DX_Dynamic_CurrentDataSend</code> by <code>TakeDynamicRequest</code>. This stage splits that upload into transfers; it does not count the full pose again for each request.

<code>DynamicRoutine</code> '''does not run DMA'''. It prepares requests for <code>VRAMDMA</code> to process during NMI.

=== What the sprite keeps ===

Sprite routines store the usable pose's hash index, not a separate copy of its graphics. The index lets them look up its VRAM block and update its last-use time.

If a new pose cannot be loaded:

* A valid previous pose is kept, and its last-use time is updated to protect it.
* If no valid pose has ever been available, the code must not draw as though the request succeeded.
* Calls supporting fallback to the previous pose may return carry set because a pose is still usable, even though the change has not completed.

Animation and movement remain the sprite's responsibility. The cache reuses or prepares the requested graphics.

=== Example: two sprites request the same pose ===

Suppose two visible sprites, A and B, need dynamic pose <code>$0005</code>. Their palettes are ready, the pose is not yet in VRAM, and enough space and data budget remain.

# '''Sprite A requests the pose.''' Lookup does not find <code>$0005</code> in the cache. The system chooses space, registers the pose, and prepares its graphics transfers. A stores the entry index in <code>!LastPoseHashIndex,x</code>. The graphics have not been copied to VRAM yet.
# '''A prepares its drawing.''' The drawing routine uses the registered entry to calculate tile numbers for that VRAM space and writes positions and properties to the OAM buffers.
# '''Sprite B requests the same pose.''' Lookup now finds <code>$0005</code> registered, even though its transfer is pending. It updates the last-use time without scheduling another upload. B stores the same cache index in its own <code>!LastPoseHashIndex,x</code>.
# '''B prepares its drawing.''' It writes its own tiles to the OAM buffers, using the same graphics as A with its own position, palette, and flip settings.
# '''NMI updates video data.''' The pending pose transfers copy the graphics to VRAM, and the game transfers the OAM buffers. Both sprites use the same uploaded graphics in the next displayed frame.

Only one pose upload is prepared, even though two sprites use it. That upload may require several DMA transfers, depending on the graphics layout in VRAM.

Here, a pose being '''available''' during logic means it has a registered entry, allocated space, and an upload prepared for NMI. If its graphics were already in VRAM, they are reused directly without preparing another transfer.

If A's request were rejected, the new pose would not be registered and no upload would be pending. A would use its previous pose if available; otherwise, it would have no pose to draw. B would need to handle its own request and would not find an entry created by A's rejected attempt.

== Palette effects: PalettesEffects ==

The system keeps the original colors so it can change effects, combine them, or restore the unaffected palette. An already affected result must not be treated as the original palette.

=== Color buffers ===

{| class="wikitable"
! Variable or buffer !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 per color || Base colors in SNES format, with 2 bytes per color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 per color || Base colors split into red, green, and blue, with 3 bytes per color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 per color || Base colors split into hue, saturation, and lightness, with 3 bytes per color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 per color || SNES-format result, ready for a CGRAM transfer request. Corresponds to the game's palette buffer.
|}

=== Per-palette flags ===

Each bit in these flags corresponds to one palette. <code>BG</code> variables cover 0–7; <code>SP</code> variables cover 8–F.

{| class="wikitable"
! Variables !! Total bytes !! Bytes per value !! Meaning
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> and <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the SNES-format color base has been prepared.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> and <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the base has been converted to RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> and <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the base has been converted to HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> and <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the global effect result is ready.
|}

These flags avoid repeating conversions and calculations whose results remain valid.

=== Preparing a base ===

# Checks whether the palette already has a registered base.
# If not, gets the colors from the game's buffer. An explicit upload, such as <code>TransferPalette</code>, can supply that base directly.
# Checks whether the effect needs RGB or HSL.
# If that conversion is missing, prepares it and marks it as available.

If only the effect changes, the base may remain valid. If the original colors change, upload calls update the base and invalidate conversions and results that must be recalculated.

=== Effect data ===

The ID selects data from the tables generated during installation:

* <code>Types</code>: calculation to perform.
* <code>Value1</code>, <code>Value2</code>, and <code>Value3</code>: channel values, or a transition's target palette address.
* <code>Ratio1</code>, <code>Ratio2</code>, and <code>Ratio3</code>: how much of each change to apply.

Channels range from 0 to 31. Ratios range from 0 to 127: 0 keeps the source unchanged, and 127 fully applies the selected change.

Calculations run outside NMI. NMI transfers the resulting colors.

=== Global effect ===

{| class="wikitable"
! Variable !! Total bytes !! Bytes per value !! Purpose
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selects the global effect. 0 restores the base colors.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; one bit per palette || Selects palettes 0–7 to receive the effect.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; one bit per palette || Selects palettes 8–F to receive the effect.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Last global effect ID processed for each palette.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controls whether the fixed color and color 0,0 are affected.
|}

For each enabled palette, the manager:

# Checks whether the effect result needs an update.
# Prepares the RGB or HSL base if missing.
# Calculates the effect if the previous result is no longer valid.
# Prepares SNES-format colors and requests their transfer.
# Records the processed ID when the corresponding upload is accepted.

If the effect and base remain unchanged, recalculation is unnecessary. Changing the global ID invalidates previous results, but not necessarily the RGB and HSL bases.

Global ID 0 also requires an update: the system must upload the base colors again to remove the previous effect.

=== Local effects and concatenation ===

A resource can have its own effect and also receive the global effect. For example, a sprite can change hue and then darken along with the level.

The order is:

# Prepare the local effect result.
# Use it as the global effect's base through the concatenation call.
# Calculate the global effect on that base.
# Upload the combined result without first displaying the local-only version.

* Use RGB concatenation for RGB effects.
* Use HSL concatenation for HSL effects.
* Resources sharing a CGRAM destination share its colors. To display two different local effects, they need destinations that can keep both results separately.

=== If the transfer is rejected ===

* Calculating an effect does not mean it is already in CGRAM.
* If the transfer is rejected, the manager can retry the update.
* Where supported, the previous usable result is kept until it can be replaced.
* Do not upload the unaffected original colors first: they could appear for one frame before the correct result.

== How the systems work together ==

A dynamic sprite brings these tasks together:

# Its logic selects the pose and palette version.
# Palette assignment finds a usable palette and prepares colors if needed.
# The cache protects the loaded pose or prepares a new upload.
# Drawing writes the pose's tiles to the OAM buffers.
# The effect manager prepares pending global changes.
# NMI performs the requested graphics and color transfers.

Sharing graphics, sharing a palette, and sharing a drawing routine are three different things. Dynamic Xtreme can take advantage of each without requiring resources to share the others.

es/Dynamic Xtreme internal workings

2026-10-25T22:12:50Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_internal_workings}}

En este artículo se explica cómo funciona Dynamic Xtreme, desde la preparación de los recursos al instalarlo hasta la carga y el dibujo de una pose durante el juego.

== Qué prepara la instalación ==

Antes de que un sprite pueda usar sus gráficos o una paleta, Dynamic Xtreme tiene que guardarlos en la ROM y preparar la información para encontrarlos. Lo mismo ocurre con cualquier otro recurso dinámico que hayas añadido.

Para hacerlo, la herramienta lee los DynamicInfo, DrawInfo y PaletteEffect. Cada archivo aporta una parte distinta: qué recursos se van a cargar, cómo se dibujan las poses y qué cambios de color se pueden aplicar.

Gracias a esta preparación se generan defines en <code>DXDefines.asm</code> que permiten utilizar los recursos y ejecutar fácilmente las rutinas necesarias.

=== DynamicInfo: recursos y datos de carga ===

Un DynamicInfo reúne los gráficos de poses, las paletas y los recursos generales que necesita un sprite u otro código. Si incluye gráficos de poses dinámicas, la herramienta los organiza para que puedan cargarse con la distribución de tiles que espera el sistema.

Por cada pose guarda varios datos en tablas separadas. Todas mantienen el mismo orden: la entrada de una pose en una tabla corresponde a esa misma pose en las demás. En la tabla siguiente, '''N''' es la cantidad de poses dinámicas instaladas.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>PoseSize</code> || 2 × N || 2 || La cantidad de datos que utiliza cada pose, en bytes. Se utiliza para comprobar si su carga cabe en el presupuesto del frame.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Cuántos bloques de 16×16 hay que reservar en VRAM para la pose. No siempre coincide exactamente con los bytes que se copian, porque una pieza incompleta también puede necesitar un bloque de espacio.
|-
| <code>PoseResource</code> || 3 × N || 3 || La dirección de los gráficos de cada pose en ROM. Incluye el banco, de modo que el código de carga pueda encontrar su origen completo.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; dos valores por pose || Dos tamaños por pose, correspondientes a los dos tramos en que pueden dividirse sus gráficos. La rutina de carga utiliza esos tamaños para repartirlos correctamente en VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || El desplazamiento en VRAM desde el comienzo del primer tramo hasta el comienzo del segundo. Permite colocar el segundo tramo donde corresponde, aunque el primero termine con una fila incompleta.
|}

Estas tablas describen todas las poses instaladas, no solo las que están en pantalla. Más adelante, la caché guarda por separado cuáles están cargadas y dónde quedaron.

Por ejemplo, si se solicita una pose que todavía no está en VRAM, el sistema consulta cuántos bytes necesita cargar, busca espacio para sus bloques y utiliza la dirección y los datos de sus tramos para preparar la carga.

==== Tablas de paletas ====

Las paletas declaradas en los DynamicInfo se reúnen en <code>PaletteTable</code>. Si '''P''' es la cantidad de entradas de las listas de paletas de los DynamicInfo:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID de cada paleta.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || Dirección de sus colores en ROM.
|}

P cuenta las entradas de las listas, no solo las paletas distintas: una paleta compartida puede aparecer en más de un DynamicInfo.

Las dos listas siguen el orden de las paletas de los DynamicInfo. El define de offset de cada DynamicInfo indica dónde comienza su lista dentro de ellas. Al elegir una versión, el sistema suma ese índice al offset y obtiene tanto el ID como la dirección de los colores elegidos.

El ID permite reconocer y compartir una paleta; la dirección permite cargarla. No son el número de paleta de pantalla: una misma paleta instalada puede terminar, por ejemplo, en la paleta 9 o en la C según la asignación.

==== Recursos generales y defines ====

Los archivos declarados en <code>Resources</code> se guardan en ROM. Su dirección y la cantidad de bytes que ocupan pueden consultarse mediante los defines generados en <code>DXDefines.asm</code>. Por ejemplo, para <code>my_resource.bin</code> se generan:

* <code>!ResourceMyResource</code>: dirección del recurso en ROM.
* <code>!ResourceMyResourceSize</code>: cantidad de bytes que ocupa.
* <code>!ResourceIDMyResource</code>: ID del recurso.

El nombre se normaliza en PascalCase: se eliminan espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra.

=== DrawInfo: datos y rutinas de dibujo ===

El DrawInfo describe cómo está formada una pose: qué tiles tiene, dónde se coloca cada uno, qué tamaño utiliza y cómo cambia al voltearse.

Al instalarlo, Dynamic Xtreme genera rutinas de dibujo optimizadas según los parámetros que utilizan los tiles. Tiene en cuenta, por ejemplo, si necesitan desplazamientos X e Y, si comparten el mismo tamaño, si utilizan propiedades comunes y si requieren volteos.

De esta forma, la rutina realiza el trabajo que necesita ese dibujo sin añadir el manejo de opciones que no utiliza. Varias poses pueden compartirla si necesitan el mismo tratamiento; eso no significa que compartan también sus gráficos o su ID.

La relación entre una pose y su dibujo se guarda en estas tablas. '''D''' es la cantidad de poses de dibujo y '''R''' la cantidad de rutinas generadas:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>TableOffset</code> || 2 × D || 2 || Dónde comienzan los datos de la pose dentro de las tablas de su rutina de dibujo. Así se localizan sus tiles y desplazamientos sin recorrer las poses anteriores.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || La cantidad de tiles de la pose menos uno. Una pose de cuatro tiles guarda 3; la rutina utiliza ese valor para recorrer sus piezas.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Qué rutina de dibujo utiliza cada pose. Las poses con características compatibles pueden apuntar al mismo ID de rutina.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 por rutina || Las direcciones de las rutinas de dibujo. El ID de rutina permite encontrar aquí el código que debe ejecutarse.
|}

Cada rutina tiene, además, las tablas que necesitan sus poses. Aquí '''T''' es la cantidad de entradas de cada tabla de la rutina:

{| class="wikitable"
! Datos !! Bytes totales !! Bytes por valor !! Qué describen
|-
| <code>Tiles</code> || T, si se genera || 1 || Los números de tile que forman la pose.
|-
| <code>Properties</code> || T, si se genera || 1 || Las propiedades de cada pieza, como los volteos y su prioridad respecto a las capas.
|-
| <code>XDisplacements</code> y <code>YDisplacements</code> || T por tabla, si se genera || 1 || La posición de cada tile respecto al punto de origen de la pose.
|-
| Tablas de desplazamientos para los volteos || T por tabla, si se genera || 1 || Las posiciones que deben utilizarse al voltear la pose cuando necesita una distribución distinta.
|-
| <code>Sizes</code> || T, si se genera || 1 || El tamaño de cada tile: 8×8 o 16×16.
|}

No todas estas tablas tienen que aparecer en todas las rutinas. Si un dato es igual para todas las piezas o puede obtenerse de un valor común, la herramienta puede generar una rutina que lo utilice directamente.

La optimización se hace durante la instalación. Si todos los tiles tienen el mismo tamaño, por ejemplo, la rutina puede utilizar ese valor común sin leer un tamaño distinto para cada pieza.

=== PaletteEffect: datos de los efectos ===

Un archivo PaletteEffect contiene una lista de cambios de color. La instalación les asigna IDs y guarda sus datos en <code>PaletteEffectsTable</code>.

Como en las tablas de poses, los datos de cada efecto mantienen la misma posición en las distintas listas. Los IDs de efectos comienzan en 1; el ID 0 se utiliza para indicar que no hay efecto global. En la tabla, '''E''' es la cantidad de efectos instalados; el conjunto ocupa '''2 + 7 × E bytes'''.

{| class="wikitable"
! Parte de la tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>Length</code> || 2 || 2 || La cantidad de efectos instalados.
|-
| <code>Types</code> || E || 1 || El tipo de cada efecto, por ejemplo <code>MixH</code>, <code>MixS</code> o <code>PalTransitionRGB</code>. Indica qué cálculo debe realizarse.
|-
| <code>Value1</code>, <code>Value2</code> y <code>Value3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Los valores de los canales que utiliza el efecto. En una transición, estos tres bytes guardan la dirección de la paleta de destino, no valores de canales.
|-
| <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Cuánto se aplica el cambio en cada componente. Van de 0 a 127.
|}

Si el efecto es una transición hacia otra paleta, la herramienta también prepara esa paleta. Convierte sus colores al formato RGB o HSL que necesita la transición y los guarda en ROM. Durante el juego se puede utilizar ese destino sin tener que convertirlo de nuevo en cada llamada.

Estas paletas de transición son distintas de las paletas normales que se cargan a CGRAM: contienen tres componentes por color y se utilizan para calcular el efecto.

=== Cómo encuentra el código los recursos instalados ===

<code>DXDefines.asm</code> publica los IDs, direcciones, tamaños y offsets que necesitan los recursos. Por ejemplo, <code>!DynamicPoseIDMySpriteIdle</code> identifica una pose y <code>!PaletteEffectIDMyEffect0</code> identifica el primer efecto de un archivo.

Los nombres se normalizan en PascalCase: se eliminan separadores como espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra. <code>my_sprite</code>, por ejemplo, pasa a <code>MySprite</code>.

También se genera <code>BufferTable</code>, que guarda las direcciones de los bloques donde se insertaron los recursos. Cada dirección ocupa 3 bytes y se añade un valor final <code>$FFFFFF</code> de otros 3 bytes. Para B bloques, ocupa <code>3 × (B + 1)</code> bytes. La herramienta utiliza esa información para localizar los datos de una instalación anterior al reinstalar.

Una reinstalación puede cambiar IDs y direcciones. Por eso hay que volver a insertar los sprites, bloques y códigos UberASM que utilizan los defines generados.

== El trabajo de cada frame ==

En la lógica principal se ejecutan el jugador, los sprites y los demás códigos del modo de juego. Los que utilizan Dynamic Xtreme solicitan las poses y paletas que necesitan, preparan los efectos locales y llaman a las rutinas de dibujo. Las cargas que se aceptan quedan anotadas para transferir sus datos durante NMI.

Al terminar esa lógica, el código de game mode de Dynamic Xtreme realiza las tareas que correspondan a las opciones habilitadas: prepara las actualizaciones de VRAM de la optimización de Kevin, mantiene el estado de las paletas y calcula los efectos globales pendientes.

Después, durante NMI, Dynamic Xtreme realiza estas tareas en orden, según las funcionalidades habilitadas:

# Pone <code>DX_Dynamic_CurrentDataSend</code> en 0.
# Incrementa <code>DX_Timer</code>.
# Incrementa <code>DX_SyncTimer</code> si la acción no está congelada ni el juego está en pausa.
# Ejecuta las transferencias de gráficos a VRAM.
# Ejecuta las transferencias de colores a CGRAM.
# Actualiza el color 0,0 si el sistema de efectos tiene un resultado pendiente.

El orden que seguiremos para explicarlo es, por tanto, '''lógica principal → tareas al terminar el game mode → transferencias durante NMI'''.

=== Lógica principal ===

Cada recurso decide qué necesita. Un sprite puede cambiar de pose, una animación puede pedir nuevos gráficos y un código UberASM puede cargar una paleta o seleccionar un efecto.

Si la pose solicitada ya está cargada, Dynamic Xtreme actualiza su tiempo de último uso para protegerla del reemplazo y no vuelve a cargar sus gráficos. Si no está cargada, comprueba el presupuesto de datos del frame y busca espacio disponible en VRAM antes de preparar su carga.

El dibujo también se prepara en esta parte: las rutinas escriben en los buffers OAM la posición, los tiles y las propiedades de las piezas que se mostrarán.

Una solicitud puede rechazarse, por ejemplo si no queda presupuesto para sus datos. El recurso que la pidió debe comprobar el resultado y decidir si conserva lo anterior o vuelve a intentarlo después. Una carga rechazada no queda guardada automáticamente para otro frame.

=== Tareas de game mode ===

En esta parte se realizan las siguientes tareas, según las funcionalidades habilitadas.

'''Antes de ejecutar la lógica del juego:'''

# Si está habilitado <code>ControllerOptimization</code>, se ejecuta la rutina del control aquí en lugar de hacerlo en NMI.
# Se comprueba si Dynamic Xtreme debe funcionar en el game mode actual. Si no debe hacerlo, se reinician sus variables. Esto ocurre cada frame que se permanezca en un modo no permitido.

Después se ejecuta la lógica normal del juego, incluidos los sprites y los códigos que solicitan cargas o cambios de paleta.

'''Cuando termina esa lógica:'''

# Si está habilitada la optimización de VRAM de Kevin, se ajustan los destinos de las actualizaciones de Lunar Magic antes de que se transfieran.
# Se ponen en 0 los indicadores de actualización de las paletas y se resta 1 a sus temporizadores de protección si todavía son mayores que 0. Esta parte se omite durante la pausa y en los modos no permitidos.
# Se aplican los efectos globales a las paletas que necesitan actualizarse y se preparan las transferencias de sus colores. Esta parte también se omite si la comprobación anterior impide continuar.

Las copias a VRAM y CGRAM se realizan después, durante NMI. Aquí se deja preparado lo que se va a copiar.

=== Game modes permitidos ===

Dynamic Xtreme utiliza dos comprobaciones de game mode:

* '''Sistema general:''' <code>Routines_AllowedGameMode</code>, publicado como <code>!AllowedGameMode</code>. Se utiliza para decidir si se reinicializa el sistema, si se procesa su NMI y si se realizan las tareas de paletas. Las macros de asignación de paletas también consultan esta comprobación cuando necesitan procesar una carga del DynamicInfo.
* '''Rutinas de sprites:''' <code>DXAllowedGameMode</code> utiliza una tabla distinta. La carga de poses mediante <code>!Upload</code> y sus macros generales tiene una tabla con los mismos valores para decidir si procesa una solicitud nueva.

Por tanto, que el sistema general esté habilitado no significa que todas las funciones de sprites acepten cargas nuevas en ese modo. Esta tabla muestra las comprobaciones actuales; los IDs están en hexadecimal:

{| class="wikitable"
! Game mode !! Pantalla o etapa de SMW !! Sistema general !! DXAllowedGameMode / solicitudes nuevas de Upload
|-
| <code>$06</code> || Apertura del foco de la pantalla de título. || Sí || No
|-
| <code>$07</code> || Pantalla de título. || Sí || Sí
|-
| <code>$08</code> || Selección de partida. || Sí || No
|-
| <code>$09</code> || Borrado de partida. || Sí || No
|-
| <code>$0A</code> || Selección de uno o dos jugadores. || Sí || No
|-
| <code>$0C</code> || Carga del overworld. || Sí || No
|-
| <code>$0D</code> || Aparición gradual del overworld. || Sí || No
|-
| <code>$0E</code> || Overworld. || Sí || Sí
|-
| <code>$12</code> || Preparación del nivel. || Sí || No
|-
| <code>$13</code> || Aparición gradual del nivel. || Sí || No
|-
| <code>$14</code> || Juego dentro del nivel. || Sí || Sí
|-
| <code>$15</code> || Desvanecimiento hacia Game Over / Time Up. || Sí || No
|-
| <code>$1B</code> || Escena de castillo o créditos. || No || Sí
|-
| <code>$1C</code> || Desvanecimiento hacia la casa de Yoshi de los créditos. || Sí || No
|-
| <code>$1D</code> || Carga de la casa de Yoshi de los créditos. || Sí || No
|-
| <code>$1E</code> || Aparición gradual de la casa de Yoshi de los créditos. || Sí || No
|-
| <code>$1F</code> || Casa de Yoshi de los créditos. || Sí || Sí
|-
| <code>$24</code> || Aparición gradual de la presentación de enemigos. || Sí || No
|-
| <code>$25</code> || Presentación de enemigos de los créditos. || Sí || Sí
|-
| <code>$29</code> || Pantalla «The End». || No || Sí
|-
| Los demás valores entre <code>$00</code> y <code>$2F</code>. || — || No || No
|}

Los nombres de las etapas corresponden a los [https://github.com/IsoFrieze/SMWDisX/blob/master/bank_00.asm game modes de SMW documentados en SMWDisX]; los permisos se obtienen de las tablas de Dynamic Xtreme.

Cuando <code>Upload</code> no permite una solicitud nueva, comprueba si el recurso conserva una pose anterior. Si existe, actualiza su tiempo de último uso y devuelve carry activado; si no existe, devuelve carry desactivado. No solicita otra pose en ese camino.

Los modos <code>$1B</code> y <code>$29</code> muestran por qué deben distinguirse ambas columnas: pasar la comprobación de sprites no habilita el NMI del sistema general ni evita que el game mode reinicialice sus variables. La columna de sprites no debe interpretarse como una garantía de funcionamiento completo en esos modos.

=== Transferencias durante NMI ===

NMI es una interrupción que SNES puede generar al comenzar VBlank, después de dibujar la parte visible de la pantalla. El juego aprovecha ese intervalo para actualizar gráficos, colores y otros datos de video.

'''La CPU ejecuta tanto la lógica del juego como la rutina NMI.''' Durante la lógica del juego, mueve sprites y prepara las solicitudes de carga. Al comenzar VBlank, una interrupción NMI puede detener temporalmente esa lógica para ejecutar las actualizaciones de video. Cuando termina la rutina NMI, la CPU retoma el código que había interrumpido.

Este es el recorrido habitual de un frame:

{| class="wikitable"
! Momento !! Qué hace la CPU !! Qué ocurre con los gráficos
|-
| Lógica del juego
| Mueve sprites, selecciona poses, calcula efectos y prepara el dibujo.
| Las solicitudes aceptadas se guardan en las listas de transferencias.
|-
| VBlank, durante NMI
| Ejecuta la rutina NMI y configura las transferencias DMA.
| Se copian los gráficos a VRAM, los colores a CGRAM y los datos de OAM a su memoria correspondiente.
|-
| Al terminar NMI
| Retoma el código interrumpido.
| Los datos actualizados se utilizan al dibujar la siguiente imagen.
|}

La tabla resume el recorrido habitual; durante slowdown, SMW puede ejecutar un NMI reducido, como se explica en el apartado de <code>DX_Timer</code>.

En los modos permitidos, la rutina de Dynamic Xtreme realiza estas tareas en orden, según las funcionalidades habilitadas:

# Pone <code>DX_Dynamic_CurrentDataSend</code> en 0 para contar las solicitudes del siguiente ciclo de lógica. Las transferencias ya preparadas siguen guardadas en sus listas.
# Incrementa <code>DX_Timer</code>.
# Comprueba <code>$9D</code> y <code>$13D4|!addr</code>. Si ambos están en 0, incrementa <code>DX_SyncTimer</code>.
# Ejecuta las transferencias pendientes a VRAM, si está habilitado <code>GraphicsChange</code>.
# Ejecuta las transferencias pendientes a CGRAM, si está habilitado <code>PalettesChange</code>.
# Si está habilitado <code>PalettesEffects</code>, ejecuta la actualización del color 0,0 cuando hay un resultado pendiente.

Para realizar las copias se utiliza DMA. NMI lee cada carga de las listas, configura desde dónde se copiarán los datos, cuántos bytes se copiarán y dónde se colocarán, y ejecuta la transferencia.

El tiempo de VBlank es limitado y SMW también lo necesita para sus actualizaciones de pantalla. Para limitar la cantidad de datos enviados en un frame y evitar flickering, Dynamic Xtreme utiliza <code>DX_Dynamic_CurrentDataSend</code>, que cuenta los bytes de las cargas solicitadas, y <code>DX_Dynamic_MaxDataPerFrame</code>, que establece el límite permitido. Antes de aceptar una carga normal, se comprueba que sus bytes no hagan superar ese límite.

==== Las listas de transferencias ====

Cada transferencia guarda el origen de los datos, su banco, la cantidad de bytes y el destino en VRAM o CGRAM.

Al realizar las copias, NMI recorre las listas desde la última entrada hacia la primera y después las vacía. Esto no borra los gráficos o colores cargados: permanecen en su destino hasta que otro código los cambie.

La lista de VRAM utiliza 0 cuando no tiene entradas. La de CGRAM utiliza <code>$FF</code>, porque guarda el índice de la última entrada en lugar de guardar directamente su cantidad.

Si dos códigos escriben sobre el mismo destino, deben coordinar sus cargas. El orden de las solicitudes no debe utilizarse como sustituto de decidir qué recurso puede ocupar cada espacio.

Normalmente, el recurso se lee desde ROM. Si el recurso se encuentra en un buffer en RAM, el usuario debe conservar su contenido hasta que NMI realice la transferencia. Por ejemplo, si prepara una paleta en RAM, no debe modificar ni reutilizar ese buffer antes de que se copie. La lista guarda su dirección, no una copia de sus datos; Dynamic Xtreme no protege el buffer contra cambios realizados por otros códigos.

==== Presupuesto de datos ====

Las macros de transferencia, como <code>%TransferToVRAM()</code> y <code>%TransferToCGRAM()</code>, comprueban cuántos bytes se han solicitado mediante <code>DX_Dynamic_CurrentDataSend</code>. Si al añadir la nueva carga se supera <code>DX_Dynamic_MaxDataPerFrame</code>, la rechazan. Si la aceptan, suman sus bytes al contador.

El límite predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Su objetivo es evitar flickering por enviar demasiados datos en un mismo frame. Es un límite de cantidad de datos, no una medida exacta del tiempo que tarda cada transferencia.

<code>DX_Dynamic_CurrentDataSend</code> lleva la cuenta de los bytes solicitados. La comprobación <code>CurrentDataSend + bytes del recurso > MaxDataPerFrame</code> impide aceptar una carga normal que supere el presupuesto y limita así los datos que se transferirán durante VBlank.

En las solicitudes de poses dinámicas, la falta de presupuesto y la falta de espacio utilizable en VRAM devuelven el mismo resultado de fallo. La llamada no indica cuál de las dos causas impidió la carga. Un fallo tampoco significa que se haya sobrecargado VBlank: si se debe al presupuesto, la carga se rechazó precisamente para evitar esa sobrecarga.

Estas macros tienen variantes como <code>%ForcedTransferToVRAM()</code> y <code>%ForcedTransferToCGRAM()</code>, que aceptan la carga sin comprobar si supera el límite. Sus bytes también se suman a <code>DX_Dynamic_CurrentDataSend</code>, por lo que reducen lo que queda disponible para las siguientes cargas normales. Se utilizan para cargas prioritarias, como las del jugador; usarlas no evita el flickering si se solicita una cantidad excesiva de datos.

Para consultar la diferencia entre el presupuesto de bytes y la capacidad de las listas, las restricciones de las transferencias y las comprobaciones que debe realizar tu código, consulta [[es/Dynamic_Xtreme_ASM_API#PPU|PPU en la API ASM]].

==== Los dos relojes ====

'''DX_Timer: protección de las solicitudes'''

<code>DX_Timer</code> avanza cuando se ejecuta la parte de NMI de Dynamic Xtreme. Además de medir cuánto lleva una pose sin utilizarse, sirve para evitar que un recurso repita sus solicitudes antes de que se procesen las anteriores.

No siempre hay un ciclo de lógica por cada ejecución completa de NMI. Durante slowdown, SMW puede ejecutar una versión reducida de NMI, y puede haber dos ciclos de lógica sin que entre ellos se hayan procesado las listas de transferencias de Dynamic Xtreme.

Sin una protección, un recurso podría añadir otra vez sus cargas a esas listas. Las solicitudes repetidas ocuparían más espacio y podrían provocar flickering.

Para evitarlo, las rutinas de carga de poses para sprites comparan <code>DX_Timer</code> con el valor de dos bytes guardado por ese sprite, normalmente llamado <code>SafeFrame</code>. En los aliases de sprites se utiliza <code>!SafeFrameLowByte,x</code> y <code>!SafeFrameHighByte,x</code>.

El proceso es el siguiente:

# '''Compara los relojes.''' Si <code>SafeFrame</code> coincide con <code>DX_Timer</code>, ese sprite ya procesó su carga de poses con ese valor del reloj. La rutina omite una nueva solicitud.
# '''Guarda el intento antes de procesarlo.''' Si los valores son distintos, copia <code>DX_Timer</code> a <code>SafeFrame</code> y después comprueba si puede reutilizar la pose o necesita solicitar otra.
# '''Comprueba el resultado.''' Si necesita una pose nueva, la solicitud puede aceptarse o rechazarse. Aunque sea rechazada, el valor guardado en <code>SafeFrame</code> no se deshace.

Por tanto, <code>SafeFrame</code> indica '''cuándo se procesó el último intento''', no cuándo se consiguió cargar una pose. Si la carga falla, volver a ejecutar la rutina con el mismo <code>DX_Timer</code> no permite intentarla otra vez, aunque entre ambas llamadas haya cambiado la pose deseada o el espacio disponible.

En <code>!Upload</code> y <code>!UploadWithoutPoseOffset</code>, tanto una solicitud rechazada como una llamada omitida por esta protección utilizan el mismo camino de respaldo:

* Si <code>!LastPoseHashIndex,x</code> es distinto de <code>$FF</code>, actualizan el tiempo de último uso de esa pose para protegerla del reemplazo y devuelven carry activado. El sprite puede seguir dibujando la última pose disponible.
* Si contiene <code>$FF</code>, no existe una pose de respaldo y devuelven carry desactivado.

Por ejemplo, durante slowdown puede ocurrir esta secuencia:

# <code>DX_Timer = $0030</code>. El sprite guarda <code>$0030</code> en su <code>SafeFrame</code> e intenta obtener una pose nueva. No queda presupuesto de datos y la solicitud falla; conserva la pose anterior si tiene una.
# SMW ejecuta otro ciclo de lógica sin que se haya procesado el NMI de Dynamic Xtreme. El reloj sigue en <code>$0030</code>. La siguiente llamada del mismo sprite detecta la coincidencia y no repite la solicitud.
# Cuando se ejecuta el NMI de Dynamic Xtreme, <code>DX_Timer</code> avanza a <code>$0031</code>. En la siguiente llamada, los relojes ya no coinciden y el sprite puede volver a intentarlo. La solicitud rechazada no se reintenta sola: el código del sprite debe volver a llamar a la rutina.

Esta protección está activada en los aliases de carga de poses para sprites. En [[es/Dynamic_Xtreme_ASM_API#GeneralUpload|GeneralUpload]] y [[es/Dynamic_Xtreme_ASM_API#Upload (macro general)|Upload (macro general)]] se controla con <code>safeCheck</code>; el respaldo de la pose anterior se controla por separado con <code>checkLast</code>. [[es/Dynamic_Xtreme_ASM_API#TakeDynamicRequest|TakeDynamicRequest]] y las [[es/Dynamic_Xtreme_ASM_API#PPU|macros de transferencia PPU]] no realizan esta comprobación de <code>SafeFrame</code> por ti.

<code>DX_Timer</code> continúa avanzando durante la pausa cuando se ejecuta esa parte de NMI.

'''DX_SyncTimer: animaciones sincronizadas'''

La función principal de <code>DX_SyncTimer</code> es dar a los sprites un reloj común para sus animaciones. Por ejemplo, varios sprites que utilizan las mismas poses pueden calcular con este reloj qué pose les corresponde cada cuatro frames.

Así todos cambian al mismo tiempo y solicitan la misma pose. La primera solicitud puede necesitar cargarla; las demás la reutilizan sin programar otra carga de sus gráficos. Esto ahorra transferencias DMA y datos enviados por frame.

Si cada sprite llevara un reloj independiente, podrían terminar usando poses distintas de la misma animación al mismo tiempo y necesitar más cargas y espacio de VRAM.

<code>DX_SyncTimer</code> se detiene durante la pausa y cuando se congela la acción, para que las animaciones sincronizadas también se detengan.

== Carga de gráficos: GraphicsChange ==

<code>GraphicsChange</code> guarda en RAM una lista de solicitudes de carga. Durante NMI se recorren esas solicitudes y se copian sus datos a VRAM.

=== Variables de la lista ===

En esta tabla, '''V''' es el valor de <code>!VRAMTransferSize</code>: 64 por defecto. Las cuatro tablas de solicitudes reservan V bytes cada una; con entradas de 2 bytes, ese valor deja espacio para 32 solicitudes. Junto con el contador, reservan <code>1 + 4 × V</code> bytes: 257 por defecto.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Cantidad de solicitudes pendientes. El valor 0 indica que la lista está vacía.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 por defecto || 2 || Dirección de origen de cada solicitud, sin el banco.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 por defecto || 2 reservados; banco de 1 byte || Banco del origen.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 por defecto || 2 || Cantidad de bytes que se copiarán.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 por defecto || 2 || Dirección de destino en VRAM.
|}

Las tablas mantienen el mismo orden: la primera entrada de cada tabla pertenece a la primera solicitud, la segunda a la segunda, etc. Cada entrada de estas tablas ocupa 2 bytes, por lo que se avanza con desplazamientos de <code>$00</code>, <code>$02</code>, <code>$04</code>, etc.

Estos nombres representan direcciones de RAM calculadas en <code>DXDefines.asm</code>. Sus direcciones pueden cambiar según la configuración y las funcionalidades habilitadas.

=== Añadir una solicitud ===

La macro <code>%TransferToVRAM()</code> realiza los siguientes pasos:

# Calcula cuántos bytes habría en total al añadir la nueva carga a <code>DX_Dynamic_CurrentDataSend</code>.
# Compara el resultado con <code>DX_Dynamic_MaxDataPerFrame</code>. Si lo supera, devuelve el carry desactivado y no añade la solicitud.
# Utiliza <code>DX_PPU_VRAM_Transfer_Length</code> para encontrar la siguiente entrada y aumenta ese contador en 1.
# Guarda el origen, banco, cantidad de bytes y destino en las tablas.
# Actualiza <code>DX_Dynamic_CurrentDataSend</code> con los bytes de la carga y devuelve el carry activado.

<code>%ForcedTransferToVRAM()</code> guarda los mismos datos, pero no comprueba el límite de bytes. Las variantes <code>FromAddr</code> y <code>Resource</code> facilitan obtener el origen desde una dirección completa o desde los defines de un recurso.

Añadir una solicitud no copia los gráficos inmediatamente: deja la información preparada para NMI.

=== Ejecutar las solicitudes durante NMI ===

La rutina <code>VRAMDMA</code>:

# Lee <code>DX_PPU_VRAM_Transfer_Length</code>. Si es 0, termina porque no hay solicitudes.
# Calcula el desplazamiento de la última entrada: <code>(Length - 1) × 2</code>.
# Lee su origen, banco y cantidad de bytes, y los coloca en los registros de DMA.
# Escribe el destino de VRAM en <code>$2116-$2117</code> e inicia la transferencia mediante <code>$420B</code>.
# Retrocede 2 bytes para procesar la solicitud anterior. Repite hasta completar la primera.
# Escribe 0 en <code>DX_PPU_VRAM_Transfer_Length</code> para indicar que la lista está vacía.

'''La lista se ejecuta del final al inicio.''' No hace falta borrar todos sus datos al terminar: al quedar su largo en 0, la próxima solicitud volverá a utilizar la primera entrada.

=== Animaciones con un destino fijo ===

El código de una animación debe:

# Elegir la imagen que corresponde al paso actual.
# Calcular su dirección de origen.
# Solicitar la copia al destino de VRAM de la animación.
# Comprobar el carry. Si se rechaza la carga, conservar la imagen anterior y volver a intentarlo.

El destino puede ser siempre el mismo. Lo que cambia es la imagen que se copia allí; la lista de transferencias no decide cuándo debe avanzar la animación.

Puedes ver un código completo en [[es/Dynamic_Xtreme_UberASM_guide#Crear_animaciones_de_gráficos|Crear animaciones de gráficos de la guía de UberASM]].

=== Carga de una pose dinámica ===

La carga de una pose utiliza la caché para no repetir transferencias de gráficos que ya están disponibles:

# Busca el ID en la tabla hash.
# Si ya está registrado, actualiza su tiempo de uso y no añade otra carga.
# Si no está, comprueba la cantidad de bytes y busca un espacio adecuado en el mapa de VRAM.
# Elige qué poses pueden reemplazarse, teniendo en cuenta su tiempo sin uso y el espacio que necesita la nueva.
# Actualiza las tablas de la caché y el mapa.
# <code>DynamicRoutine</code> divide los datos de la pose en las transferencias necesarias.
# NMI ejecuta esas transferencias.

Cada paso se desarrolla en [[#Sprites_dinámicos:_DynamicPoses|Sprites dinámicos: DynamicPoses]], incluyendo la búsqueda por hash, el mapa, la política de reemplazo y la división de la carga en filas.

== Carga y asignación de paletas: PalettesChange ==

El sistema distingue dos valores:

* '''ID de paleta:''' identifica los colores guardados en ROM.
* '''Color de destino:''' indica desde qué color de la paleta de colores de CGRAM se colocarán los colores que se carguen. Por ejemplo, <code>$91</code> comienza en el color 1 de la paleta 9.

La asignación automática permite compartir colores entre sprites sin exigir un destino fijo para cada uno.

=== Lista de cargas a CGRAM ===

En esta tabla, '''C''' es <code>!CGRAMTransferSize</code>: 64 por defecto. El conjunto reserva <code>1 + 7 × C</code> bytes, es decir, 449 con ese valor. Aunque <code>SourceBNK</code> reserva 2 × C bytes, el código utiliza un byte de banco por solicitud.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Índice de la última solicitud pendiente. <code>$FF</code> indica una lista vacía; 0 indica que hay una solicitud.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 por defecto || 2 || Dirección de origen, sin el banco.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 reservados por defecto || 1 utilizado por solicitud || Banco del origen.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 por defecto || 2 || Cantidad de bytes que se copiarán. Cada color ocupa 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 por defecto || 1 || Primer color de destino en CGRAM.
|}

Durante NMI, <code>CGRAMDMA</code>:

# Comienza por la última solicitud pendiente.
# Configura DMA con el origen y la cantidad de bytes de esa solicitud.
# Selecciona el primer color mediante <code>$2121</code> y realiza la copia.
# Continúa con las solicitudes anteriores.
# Al terminar, escribe <code>$FF</code> en <code>DX_PPU_CGRAM_Transfer_Length</code>.

Las macros <code>TransferPalette</code> también actualizan las copias de colores y el estado de efectos:

* '''Sin efecto global:''' solicitan la carga y actualizan los buffers de SMW. Así el juego no vuelve a utilizar colores anteriores durante la animación de victoria del goal.
* '''Con efecto global:''' guardan los colores originales y preparan el estado necesario para aplicarles el efecto antes de enviarlos a CGRAM.

=== Asignación automática ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || Guarda el ID asignado a cada destino. <code>$FFFF</code> indica una entrada libre y <code>$FFFE</code> una reservada.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protege cada destino del reemplazo automático mientras está en uso.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; un bit por paleta de sprites || Indica qué paletas de sprites están asignadas con efecto global habilitado. Esta condición también se compara al compartir una asignación.
|}

La búsqueda sigue este orden:

# Reutilizar una asignación con el mismo ID y una condición de efecto compatible.
# Si no existe, utilizar una entrada libre.
# Si no hay entradas libres, reemplazar una que no esté reservada y cuyo temporizador sea 0.
# Si no encuentra ninguna, indicar que la asignación falló.

Mientras el recurso utiliza la paleta, mantiene su temporizador en 2. Llegar a 0 no borra los colores: la asignación puede reutilizarse si otro recurso todavía no la reemplazó.

=== Asignación manual y versión ===

* '''Manual con carga:''' el código elige el destino y solicita sus colores.
* '''Manual sin carga:''' el código elige el destino y utiliza los colores que ya estaban preparados.
* '''Versión:''' selecciona una entrada de la lista de paletas del DynamicInfo. La última versión procesada permite comprobar si esa selección cambió.

Dos recursos que elijan el mismo destino con colores distintos deben coordinarse. Mantener la protección de una paleta no significa volver a cargar sus colores.

== Dibujo de poses: DrawingSystem ==

El dibujo prepara las piezas de una pose en OAM: qué tiles se muestran, dónde se colocan y qué propiedades utilizan. Los datos gráficos deben estar en VRAM.

=== Pasos del dibujo ===

# Busca la rutina y los datos de la pose mediante <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code> y <code>TableOffset</code>.
# Obtiene la cantidad de piezas desde <code>NumberOfTilesMinus1</code>.
# Calcula la posición de cada tile usando la posición del sprite, sus desplazamientos y los volteos que correspondan.
# Comprueba si la pieza puede verse y si queda espacio de OAM.
# Escribe su posición, número de tile, propiedades y tamaño en los buffers OAM.

El número de tile depende del dibujo:

{| class="wikitable"
! Caso !! Cómo se obtiene el tile
|-
| Pose dinámica || Se ajusta al lugar de VRAM donde quedaron cargados sus gráficos.
|-
| Pose estática || Se utiliza su número de tile fijo.
|-
| Pose que utiliza un tile común || El código debe preparar <code>!Tile</code> antes de llamar al dibujo.
|}

=== Prioridad y espacio disponible ===

* En '''LoROM''', el sistema lleva su propio control de entradas OAM disponibles.
* En '''SA-1''', utiliza la integración con MaxTile.
* La '''prioridad de dibujo''' organiza las piezas de sprites. No es la misma propiedad que determina si un tile queda delante o detrás de las capas.
* Los '''límites por línea de pantalla''' de SNES siguen existiendo. Tener una pose cargada no garantiza que puedan verse todas sus piezas.

== Jugador y Yoshi ==

=== PlayerFeatures ===

El jugador original tiene rutinas propias para elegir y cargar las piezas de sus poses. <code>PlayerFeatures</code> permite integrar ese trabajo con las cargas de Dynamic Xtreme y cambiar el origen de sus gráficos y paletas.

Con el formato original, el juego sigue eligiendo las piezas de la pose. La rutina obtiene sus direcciones desde el origen configurado y compara esas direcciones con las anteriores para cargar las que hayan cambiado.

Estas cargas utilizan transferencias forzadas y sus bytes también cuentan para las solicitudes normales posteriores. Así conservan su prioridad sin quedar fuera de la contabilidad del sistema.

La paleta del jugador tiene un tratamiento especial: combina colores y selecciones del propio juego con el origen personalizado. No funciona simplemente como sustituir una paleta completa de un sprite cualquiera.

El soporte para jugadores personalizados permite que otros sistemas administren de otra forma sus poses y dibujo. No convierte automáticamente cualquier spritesheet al formato del jugador original.

=== YoshiFeatures ===

Yoshi también carga sus gráficos por piezas. <code>YoshiFeatures</code> permite cambiar su origen manteniendo la organización que esperan sus rutinas.

El código calcula qué partes necesita y prepara sus cargas a los destinos correspondientes de VRAM. Como las del jugador, estas cargas tienen un tratamiento prioritario.

Esta opción necesita <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad. No permite evitar un conflicto del sistema del jugador habilitando únicamente las funciones de Yoshi.

== Diferencias entre LoROM y SA-1 ==

Las principales diferencias de Dynamic Xtreme entre ambas configuraciones están en la memoria utilizada para sus variables y en el sistema de dibujo:

{| class="wikitable"
! Aspecto !! LoROM !! SA-1
|-
| Memoria para las variables
| Se suele utilizar <code>Free7E2000</code> para aprovechar la RAM recuperada como espacio para las variables de Dynamic Xtreme. Si esta opción provoca problemas de compatibilidad, puede deshabilitarse y utilizar la configuración alternativa, con el espacio de RAM más ajustado.
| No utiliza <code>Free7E2000</code>. Las áreas principales de variables se encuentran en BW-RAM, en los bancos <code>$40</code> y <code>$41</code>.
|-
| Prioridades de dibujo
| Utiliza el sistema propio de Dynamic Xtreme, con dos prioridades de dibujo.
| Utiliza MaxTile, con cuatro prioridades de dibujo para los tiles.
|}

Las dos prioridades de LoROM no permiten mantener todas las distinciones de orden de las cuatro prioridades de SA-1. Por eso, algunos recursos que se dibujan correctamente en SA-1 pueden presentar un orden de dibujo diferente o incorrecto en LoROM. Estas prioridades organizan los tiles de sprites; no son la prioridad que determina si aparecen delante o detrás de las capas.

Los rangos de RAM de cada configuración se detallan en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Espacios de RAM utilizados]].

== Memoria y optimizaciones ==

=== Free7E2000 ===

SMW mantiene en RAM gráficos originales del jugador, Yoshi y ciertas animaciones. En ROMs sin SA-1, esta opción adapta las cargas para leer esos datos desde ROM.

Dynamic Xtreme aprovecha la RAM recuperada para sus variables internas. No es un espacio que quede libre para que cualquier otro código escriba encima.

SA-1 utiliza otras direcciones y desactiva esta opción. Los rangos están en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Espacios de RAM utilizados]].

=== ControllerOptimization ===

Esta opción mueve el procesamiento del control desde NMI a la parte de game mode. El objetivo es dejar más tiempo para las actualizaciones de pantalla, no añadir un frame de retraso ni cambiar los botones que recibe el juego.

=== FixedColorOptimization ===

El color fijo se utiliza en las mezclas de color de la consola. Para actualizarlo, el juego prepara sus componentes y los envía al registro correspondiente.

La optimización reemplaza esa preparación por una secuencia más corta. El color sigue enviándose a la consola, pero necesita menos trabajo durante NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic utiliza listas llamadas stripe images para actualizar partes de los mapas de tiles. Esas listas incluyen tanto los datos como la información sobre sus destinos.

La versión integrada de la optimización de Kevin prepara fuera de NMI parte del ajuste de esos destinos. Así deja menos trabajo de preparación para el momento de la transferencia.

Esta opción sustituye el uso del parche original por separado. Además, no debe desinstalarse después de instalarla; hay que tenerlo en cuenta antes de activarla.

=== StatusBarOptimization ===

La barra de estado original actualiza zonas concretas de VRAM. Esta opción prepara sus transferencias de forma más directa, reduciendo la configuración de DMA que necesita hacer durante NMI.

No añade una barra nueva. Modifica la actualización de la original y, por eso, entra en conflicto con recursos que la reemplazan, modifican o eliminan.

== Sprites dinámicos: DynamicPoses ==

El sistema funciona como una '''caché de poses en VRAM'''. No reserva una copia de los gráficos para cada sprite: guarda la pose y permite que la reutilicen todos los recursos que la necesiten.

* Una pose se carga una sola vez mientras permanezca en la caché.
* Las siguientes solicitudes actualizan su tiempo de último uso, sin añadir otra carga de sus gráficos.
* La pose no se borra cuando un recurso deja de utilizarla. Permanece allí hasta que se necesite su espacio y se elija reemplazarla.
* Si fue reemplazada y vuelve a solicitarse, tendrá que cargarse otra vez.

La elección no depende de cuánto tiempo lleva la pose desde que se cargó, sino de '''cuánto tiempo lleva sin utilizarse''' y de si su espacio sirve para la pose nueva.

=== Tres valores distintos ===

{| class="wikitable"
! Valor !! Qué identifica
|-
| ID de pose || La pose instalada. Tiene 16 bits y permite consultar sus datos en ROM.
|-
| Índice de la tabla hash || La entrada de RAM donde se registró la pose. Va de 0 a 127.
|-
| Bloque de VRAM || ID de una de las 128 posiciones para tiles de 16×16 que caben en el espacio de VRAM de sprites. Se numeran de izquierda a derecha y de arriba abajo, desde 0 hasta 127. Para una pose que ocupa varios bloques, se guarda el ID de su primer bloque.
|}

El índice de la tabla hash y el bloque de VRAM no tienen por qué coincidir. Una entrada de la tabla puede registrar una pose que empieza en cualquier bloque permitido.

=== Tablas de las poses registradas ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Cantidad de poses registradas.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Cantidad de poses registradas para cada hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || ID completo de la pose de cada entrada. <code>$FFFF</code> indica una entrada libre.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Bloque de VRAM donde comienza cada pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || Valor de <code>DX_Timer</code> de su último uso.
|}

Estas tablas ocupan '''769 bytes''' en RAM. Guardan las poses registradas durante el juego; las tablas generadas desde el DynamicInfo describen, en cambio, todas las poses instaladas.

=== Cómo se busca una pose ===

La rutina <code>DynamicPoseHashmap_FindPose</code> utiliza una tabla hash de 128 entradas. El hash permite elegir dónde empezar a buscar:

<pre>
hash = ID de pose AND $007F
</pre>

Dos IDs diferentes pueden tener el mismo hash. Por ejemplo, <code>$0005</code> y <code>$0085</code> producen <code>$05</code>. Por eso el hash no basta para confirmar que la pose está cargada: también se compara el ID completo.

La búsqueda sigue estos pasos:

# Guarda el ID solicitado y calcula su hash.
# Si <code>DX_Dynamic_Pose_Length</code> es 0, no hay poses registradas y la búsqueda termina.
# Consulta <code>DX_Dynamic_Pose_HashSize[hash]</code>. Si es 0, ninguna pose registrada tiene ese hash y también termina.
# Comienza por la entrada cuyo índice coincide con el hash.
# Lee el ID de esa entrada. Si coincide con el solicitado, encontró la pose.
# Si no coincide, continúa con la siguiente entrada de la secuencia de búsqueda.

La secuencia avanza '''15 entradas por intento''' y vuelve al comienzo al superar 127:

<pre>
siguiente índice = (índice actual + 15) AND $7F
</pre>

Con 128 entradas, ese paso permite visitar todas las posiciones antes de repetir una. Para el hash <code>$05</code>, el comienzo de la secuencia es:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

==== El contador de poses de cada hash ====

Cada hash tiene su propio contador en <code>DX_Dynamic_Pose_HashSize</code>. Por ejemplo, si hay dos poses registradas cuyo ID produce el hash <code>$05</code>, la entrada <code>DX_Dynamic_Pose_HashSize+$05</code> contiene 2.

Ese número indica '''cuántas poses con ese hash existen''', no cuántas posiciones hay que recorrer. La búsqueda utiliza una copia temporal del contador:

# Comienza con la cantidad de poses registrada para el hash solicitado.
# Recorre las posiciones de la secuencia hasta encontrar el ID solicitado o haber comprobado esa cantidad de poses con el mismo hash.
# Cada vez que encuentra una pose con ese hash, pero con otro ID, resta 1 al contador temporal.
# Las posiciones libres y las poses de otros hashes no descuentan nada: continúa buscando.
# Si el contador temporal llega a 0 sin encontrar el ID, la pose solicitada no está registrada y la búsqueda termina.

El contador de <code>DX_Dynamic_Pose_HashSize</code> no se modifica durante esta búsqueda. Solo se actualiza al añadir o retirar poses de la caché.

Por ejemplo, se busca <code>$0105</code>, que produce el hash <code>$05</code>, y el contador de ese hash vale 2:

{| class="wikitable"
! Posición visitada !! ID guardado !! Hash del ID !! Poses del hash $05 que faltan por comprobar
|-
| <code>$05</code> || <code>$0005</code> || <code>$05</code> || 1: tiene el mismo hash, pero no es el ID solicitado.
|-
| <code>$14</code> || <code>$0014</code> || <code>$14</code> || 1: es otro hash, así que no se descuenta.
|-
| <code>$23</code> || <code>$0085</code> || <code>$05</code> || 0: ya se comprobaron las dos poses con ese hash. <code>$0105</code> no está registrada.
|}

Lo habitual es que haya una o dos poses por hash. Esto permite resolver la búsqueda con pocas comprobaciones y un coste normalmente cercano a <code>O(1)</code>. No significa que siempre se visiten solo una o dos posiciones: puede haber entradas de otros hashes entre ellas. Con muchas colisiones, el recorrido puede ser más largo.

'''Una entrada libre no termina la búsqueda.''' Puede haber quedado vacía al reemplazar una pose y existir otra del mismo hash más adelante. El contador permite saber cuándo ya se comprobaron todas las poses de ese hash, incluso si hay huecos entre ellas.

==== Cuando encuentra la pose ====

<code>TakeDynamicRequest</code>:

# Obtiene el índice de la entrada encontrada.
# Escribe el valor actual de <code>DX_Timer</code> en <code>DX_Dynamic_Pose_TimeLastUse</code> para esa entrada.
# Devuelve el éxito de la solicitud, sin volver a programar la carga de sus gráficos.

Así todos los recursos que solicitan ese ID utilizan la misma pose y la mantienen protegida. No importa si el recurso es un sprite normal, cluster, extended u otro código que utiliza el sistema.

Esto también evita duplicar una carga dentro del mismo ciclo: cuando la primera solicitud se acepta, la pose ya queda registrada aunque la transferencia física se vaya a realizar durante NMI.

=== Cuando la pose no está registrada ===

<code>TakeDynamicRequest</code> continúa con la preparación de una carga nueva:

# Consulta <code>PoseSize</code> y calcula <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# Si supera <code>DX_Dynamic_MaxDataPerFrame</code>, termina con fallo, sin cambiar las poses existentes.
# Consulta <code>Pose16x16Blocks</code> para saber cuántos bloques necesita.
# Llama a <code>VRAMMap_GetBestSlot</code> para buscar un espacio adecuado.
# Si no existe un espacio utilizable, termina con fallo.
# Retira del mapa y de la tabla hash las poses que ocupen el espacio elegido.
# Busca una entrada libre de la tabla hash y registra la pose nueva.
# Actualiza el mapa de VRAM y el contador de datos del frame.
# Llama a <code>DynamicRoutine</code> para añadir las transferencias.

El presupuesto se comprueba antes de reemplazar poses. Si la nueva carga no cabe en el frame, no se libera espacio para una solicitud que no se puede atender.

==== Añadir y quitar entradas de la tabla hash ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> busca una entrada cuyo ID sea <code>$FFFF</code>, siguiendo la misma secuencia de pasos de 15.
* <code>DynamicPoseHashmap_Add</code> guarda el ID y su tiempo de uso, aumenta <code>DX_Dynamic_Pose_Length</code> y aumenta el contador de su hash.
* <code>DynamicPoseHashmap_Remove</code> escribe <code>$FFFF</code> en el ID retirado y reduce ambos contadores.

Retirar una entrada no borra por sí solo los píxeles de VRAM. Indica que esa pose dejó de estar disponible en la caché; las nuevas transferencias sobrescribirán el espacio elegido.

=== Cómo se representa el mapa de VRAM ===

El mapa representa '''128 posiciones de tiles de 16×16 en la VRAM de sprites''', numeradas de izquierda a derecha y de arriba abajo. Cada bloque es una de esas posiciones, no un tramo de 128 bytes contiguos.

Un tile de 16×16 está formado por cuatro tiles de 8×8 distribuidos en dos filas. El mapa administra las posiciones que ocupa la pose; la distribución de sus datos para cargarlos se resuelve después en <code>DynamicRoutine</code>.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Posición donde comienza la sección. El bit <code>$80</code> indica que está restringida: ese espacio no se utiliza para poses dinámicas.
|-
| <code>DX_Dynamic_Tile_Size</code>, también llamada <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || Si el bit <code>$80</code> está activo, los otros bits guardan la cantidad de posiciones de la sección menos uno. Si está desactivado, guardan el índice hash de la pose que ocupa la sección. Para saber si el espacio está restringido, se consulta <code>Offset</code>.
|}

Estas dos tablas ocupan '''256 bytes'''. Junto con las tablas de poses, el administrador utiliza '''1025 bytes''' de RAM, sin contar las listas de transferencias ni las scratch de trabajo.

=== Secciones del mapa ===

Una sección agrupa posiciones consecutivas del mapa que están restringidas, libres o utilizadas por una pose. Su información se guarda en '''la primera y la última posición'''. Esto permite saltar de una sección a la anterior sin revisar todas sus posiciones intermedias.

Los siguientes ejemplos muestran tres estados posibles para una sección de 6 posiciones, de <code>$20</code> a <code>$25</code>. Son casos alternativos, no tres secciones que ocupen el mismo espacio a la vez.

==== Ejemplo 1: sección restringida ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$A0</code> || <code>$80</code> indica restringida y <code>$20</code> indica dónde comienza.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || La sección tiene 6 posiciones: <code>($85 AND $7F) + 1 = 6</code>.
|}

Aunque el bit alto de <code>Size</code> esté activo, '''no es espacio libre para poses dinámicas''': el bit de restricción en <code>Offset</code> hace que se descarte. No se evalúa como una pose que pueda reemplazarse.

<code>DynamicPoseSpaceConfig</code> utiliza este tipo de sección para excluir las partes de SP1-SP4 que no deben utilizar los sprites dinámicos.

==== Ejemplo 2: sección libre ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || Comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || El bit <code>$80</code> indica el tamaño de una sección libre: <code>$05 + 1 = 6</code> posiciones.
|}

Esta sección sí está disponible. Puede alojar una pose que necesite hasta 6 posiciones; si se coloca una de 4, las otras 2 quedan como otra sección libre.

==== Ejemplo 3: sección utilizada por una pose ====

Supongamos que una pose de 6 bloques está registrada en la entrada hash <code>$07</code> y ocupa las posiciones <code>$20</code> a <code>$25</code>:

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || La sección comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$07</code> || El bit <code>$80</code> está desactivado: <code>$07</code> es el índice hash de la pose, no su cantidad de bloques.
|}

Para conocer la cantidad de posiciones y el tiempo sin uso:

# Se lee el ID de la pose en <code>DX_Dynamic_Pose_ID+$0E</code>. Se utiliza <code>$0E</code> porque cada ID ocupa 2 bytes y <code>$07 × 2 = $0E</code>.
# Con ese ID se consulta <code>Pose16x16Blocks</code>, que en este ejemplo contiene 6.
# Se consulta <code>DX_Dynamic_Pose_TimeLastUse+$0E</code> para calcular cuánto lleva sin utilizarse.

La entrada <code>DX_Dynamic_Pose_Offset+$07</code> guarda <code>$20</code>, relacionando esa pose registrada con su posición en VRAM.

=== Recorrido y búsqueda de espacio ===

<code>VRAMMap_GetBestSlot</code> comienza por la posición de tile de 16×16 <code>$7F</code>. Para recorrer el mapa:

# Lee <code>DX_Dynamic_Tile_Offset</code> de la posición actual.
# Obtiene el comienzo de la sección con <code>Offset AND $7F</code>.
# Evalúa esa sección y los espacios que pueda formar con otras secciones contiguas.
# Pasa a la posición <code>comienzo de la sección - 1</code>, que es la última posición de la sección anterior.
# Repite hasta llegar al comienzo del mapa.

Por ejemplo, si las últimas secciones comienzan en <code>$70</code>, <code>$60</code> y <code>$50</code>:

{| class="wikitable"
! Posición visitada !! Comienzo leído de Offset !! Próxima posición
|-
| <code>$7F</code> || <code>$70</code> || <code>$6F</code>
|-
| <code>$6F</code> || <code>$60</code> || <code>$5F</code>
|-
| <code>$5F</code> || <code>$50</code> || <code>$4F</code>
|}

Así recorre '''secciones completas''', no cada tile intermedio.

==== Qué se evalúa durante el recorrido ====

El espacio candidato puede ser '''una sección o varias secciones contiguas'''. En cada paso se comprueba:

* Si hay una sección restringida, no se utiliza ni se combina a través de ella.
* Si hay una pose protegida por su uso reciente, tampoco puede formar parte del espacio.
* Si el candidato todavía es pequeño, se puede continuar con una sección contigua para completar la cantidad de bloques necesaria.
* Si ya cabe la pose, se compara el candidato con el mejor encontrado: primero por su score de tiempo sin uso y después por el espacio suficiente más pequeño.

No se elige una sección solo por contener la pose con más tiempo sin uso. El '''espacio completo''' debe permitir cargar la pose nueva. La puntuación de varias secciones combinadas depende de la pose utilizada más recientemente dentro de ese espacio.

Durante la búsqueda se conservan estos datos temporales:

{| class="wikitable"
! Datos de trabajo !! Bytes totales !! Bytes por valor !! Para qué se usan
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 por campo || Comienzo, score y cantidad de bloques del espacio candidato actual.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 por campo || Los mismos campos para el mejor espacio encontrado.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Cantidad de bloques que necesita la pose nueva.
|}

Estos nombres utilizan scratch de trabajo, no RAM persistente adicional.

=== Política de reemplazo: tiempo sin uso y espacio suficiente ===

El sistema no elige simplemente la pose que se cargó primero. Utiliza el tiempo transcurrido desde su '''último uso''':

<pre>
tiempo sin uso = DX_Timer - TimeLastUse de la pose
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> obtiene el tamaño y una puntuación para cada región:

{| class="wikitable"
! Caso !! Puntuación y tratamiento
|-
| Región libre || <code>$FF</code>. Se favorece frente a regiones ocupadas.
|-
| Región ocupada || Tiempo sin uso, limitado a <code>$FE</code>.
|-
| Tiempo sin uso de 0 o 1 || No se puede reemplazar: la pose sigue protegida.
|-
| Región restringida || Se descarta: ese espacio no se utiliza para poses dinámicas.
|}

La protección exige '''al menos dos avances de <code>DX_Timer</code> sin utilizar la pose'''. Cada recurso que vuelve a solicitarla actualiza su tiempo de uso y vuelve a protegerla.

==== Por qué no siempre se reemplaza la pose con más tiempo sin uso ====

La pose nueva necesita espacio suficiente y contiguo. Un espacio pequeño no sirve por sí solo, aunque lleve mucho tiempo sin utilizarse.

Por ejemplo, para una pose nueva de 4 bloques:

{| class="wikitable"
! Espacio candidato !! Tiempo sin uso !! ¿Sirve?
|-
| Pose A: 2 bloques, sin espacio contiguo utilizable || 20 || No: solo deja 2 bloques.
|-
| Pose B: 4 bloques || 8 || Sí: puede alojar la pose nueva.
|}

En este caso se puede reemplazar B y conservar A. A lleva más tiempo sin uso, pero su espacio no permite atender la solicitud.

Si dos o más regiones contiguas pueden reemplazarse, el sistema puede considerarlas juntas. Para esa combinación:

* Suma sus cantidades de bloques.
* Utiliza la '''menor puntuación''' de las regiones combinadas, es decir, el menor tiempo sin uso.
* Si una está restringida o protegida, no puede utilizarla para completar el espacio.

Así una pose usada recientemente no puede quedar sobrescrita por combinarla con otra que lleva mucho tiempo sin uso.

==== Elegir entre candidatos válidos ====

# El candidato debe tener al menos la cantidad de bloques solicitada.
# Se prefiere la puntuación más alta: espacio libre o mayor tiempo sin uso.
# Si las puntuaciones son iguales, se prefiere el candidato con menos bloques, siempre que la pose quepa.
# Si puntuación y tamaño también coinciden, se conserva el candidato que ya se había elegido.

Las regiones se combinan durante la búsqueda cuando el candidato todavía es demasiado pequeño. No se juntan todas las regiones reemplazables sin tener en cuenta el tamaño solicitado.

=== Reemplazar y dividir la región elegida ===

Una vez elegido el espacio:

# <code>VRAMMap_RemovePosesInSpace</code> recorre sus regiones y retira de la tabla hash las poses que haya que reemplazar.
# <code>VRAMMap_RemoveSpace</code> representa el espacio elegido como una región libre, actualizando sus extremos.
# Se busca una entrada hash libre y se guarda el bloque de comienzo en <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registra la pose.
# <code>VRAMMap_AddPoseInSpace</code> escribe el índice hash de la pose y el comienzo de su región en el primer y último bloque.
# Si sobran bloques, crea otra región libre con el resto.

Si una región de 6 bloques aloja una pose de 4, quedan una región ocupada de 4 y una libre de 2. Dynamic Xtreme no tiene un sistema de desfragmentación de VRAM: no desplaza las poses cargadas para reunir los espacios libres.

=== DynamicRoutine: preparar las transferencias de la pose ===

En este punto ya se eligió el espacio y se registró la pose. <code>DynamicRoutine</code> convierte esa asignación en solicitudes de transferencia.

Utiliza estos datos:

{| class="wikitable"
! Dato !! Cantidad consultada por pose !! Para qué sirve
|-
| Bloque de comienzo || 1 byte || Lugar elegido por el mapa de VRAM.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes de una tabla de 256 bytes || Convierte uno de los 128 bloques en un desplazamiento de VRAM.
|-
| <code>PoseResource</code> || 3 bytes || Dirección completa de los datos de la pose en ROM.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: dos valores de 2 || Cantidad de bytes del primer y del segundo tramo.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || Desplazamiento de VRAM para el segundo tramo.
|}

==== Convertir el bloque en una dirección de VRAM ====

Los bloques de 16×16 no se convierten simplemente en un desplazamiento lineal de bytes. Cada uno utiliza tiles de 8×8 distribuidos en las filas de VRAM.

<code>OffsetToVRAMOffset</code> contempla esa distribución. Por ejemplo:

{| class="wikitable"
! Bloque !! Desplazamiento !! Dirección de VRAM
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

Estas direcciones de VRAM están expresadas en palabras de 2 bytes, no en bytes. La rutina suma la base <code>$6000</code> utilizada para los gráficos de sprites.

==== Procesar los tramos y sus filas ====

# Obtiene el origen desde <code>PoseResource</code>.
# Procesa los bytes del primer tramo mediante <code>DynamicRoutineLine</code>.
# Si el segundo tramo tiene tamaño 0, termina.
# Si existe, adelanta el origen la cantidad de bytes del primer tramo.
# Suma <code>PoseSecondLineOffset</code> al desplazamiento de VRAM y procesa el segundo tramo.

<code>DynamicRoutineLine</code> divide cada tramo según las filas y el punto de comienzo. Para un destino V expresado en palabras de VRAM, prepara:

<pre>
Final de la primera fila = (V + $0100) AND $FF00
Bytes hasta ese final = (final de la primera fila - V) × 2
Destino de la segunda parte = final de la primera fila + $0100
Bytes de la segunda parte de un grupo = $0200 - bytes de la primera
</pre>

Los tamaños son cantidades de bytes, mientras que los destinos de VRAM están expresados en palabras. Por eso se multiplica por 2 al calcular cuántos datos caben hasta el final de una fila.

La rutina utiliza tres recorridos:

* <code>.EndLine</code>: añade una solicitud final con los bytes restantes.
* <code>.TwoLinesWithEndLine</code>: añade dos solicitudes para los datos restantes, cada una con su destino y cantidad de bytes.
* <code>.TwoLines</code>: añade dos solicitudes que suman <code>$0200</code> bytes, avanza el origen y los destinos y repite con los datos que faltan.

Hay un caso directo antes del recorrido general: si el destino comienza en un límite de <code>$0100</code> palabras y el tramo tiene al menos <code>$0200</code> bytes, la rutina utiliza <code>.EndLine</code> para preparar la copia del tramo completo en una solicitud.

Por ejemplo, un tramo de <code>$0200</code> bytes que comienza en <code>$6020</code> se divide así:

{| class="wikitable"
! Solicitud !! Origen !! Destino VRAM !! Bytes
|-
| Primera || Comienzo del tramo || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Segunda || Comienzo del tramo + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Las dos solicitudes copian los 512 bytes del tramo, respetando los destinos que calcula la distribución de filas. No son dos copias completas de la pose.

Cada solicitud utiliza estas tablas:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Por cada solicitud añadida aumenta <code>DX_PPU_VRAM_Transfer_Length</code>.

La cantidad total de bytes de la pose ya se comprobó y se añadió a <code>DX_Dynamic_CurrentDataSend</code> en <code>TakeDynamicRequest</code>. Esta parte divide esa carga en transferencias; no vuelve a contar la pose completa por cada solicitud.

<code>DynamicRoutine</code> '''no ejecuta DMA'''. Deja las solicitudes preparadas para que <code>VRAMDMA</code> las copie durante NMI.

=== Qué conserva el sprite ===

Las rutinas de sprites guardan el índice hash de la pose utilizable, no una copia independiente de sus gráficos. Ese índice permite consultar su bloque de VRAM y mantener actualizado su tiempo de uso.

Si una pose nueva no puede cargarse:

* Si existe una pose anterior válida, se mantiene y se actualiza su tiempo de uso para protegerla.
* Si nunca hubo una pose válida, no se debe dibujar como si la solicitud hubiera tenido éxito.
* En las llamadas con soporte para mantener la anterior, el carry puede indicar que todavía hay una pose utilizable aunque no se haya completado el cambio.

La animación y el movimiento siguen siendo responsabilidad del sprite. La caché se ocupa de reutilizar o preparar los gráficos solicitados.

=== Ejemplo: dos sprites solicitan la misma pose ===

Supongamos que dos sprites visibles, A y B, necesitan la pose dinámica <code>$0005</code>. Sus paletas ya están listas, la pose todavía no está en VRAM y hay espacio y presupuesto para cargarla.

# '''El sprite A solicita la pose.''' La búsqueda no encuentra <code>$0005</code> en la caché. El sistema elige un espacio, registra la pose y prepara las transferencias de sus gráficos. A guarda el índice de esa entrada en <code>!LastPoseHashIndex,x</code>. Los gráficos aún no se han copiado a VRAM.
# '''A prepara su dibujo.''' La rutina de dibujo utiliza la entrada registrada para calcular los tiles que corresponden a ese espacio de VRAM y escribe sus posiciones y propiedades en los buffers OAM.
# '''El sprite B solicita la misma pose.''' La búsqueda ya encuentra <code>$0005</code> registrada, aunque su transferencia siga pendiente. Actualiza su tiempo de último uso y no programa otra carga. B guarda el mismo índice de caché en su propia <code>!LastPoseHashIndex,x</code>.
# '''B prepara su dibujo.''' Escribe sus propias piezas en los buffers OAM, utilizando los mismos gráficos que A, pero con su posición, paleta y volteo.
# '''Durante NMI se actualizan los datos de video.''' Se realizan las transferencias pendientes de la pose a VRAM y el juego transfiere los buffers OAM. En la siguiente imagen, los dos sprites utilizan los mismos gráficos cargados.

Se prepara una sola carga de la pose, aunque dos sprites la utilicen. Esa carga puede necesitar varias transferencias DMA según cómo se distribuyan sus gráficos en VRAM.

En este ejemplo, que la pose esté '''disponible''' durante la lógica significa que ya tiene una entrada y un espacio asignados, con su carga preparada para NMI. Si sus gráficos ya estaban en VRAM, se reutilizan directamente y no hay que preparar otra transferencia.

Si la solicitud de A fuera rechazada, no se registraría la pose nueva ni quedaría su carga pendiente. A utilizaría su pose anterior si tiene una; de lo contrario, no dispondría de una pose para dibujar. B tendría que resolver su propia solicitud y no encontraría una entrada creada por el intento rechazado de A.

== Efectos de paleta: PalettesEffects ==

El sistema conserva los colores originales para poder cambiar de efecto, combinarlo con otro o volver a la paleta sin efecto. No debe utilizar el resultado ya afectado como si fuera la paleta original.

=== Buffers de colores ===

{| class="wikitable"
! Variable o buffer !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 por color || Colores de base en formato SNES, con 2 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 por color || Base separada en rojo, verde y azul, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 por color || Base separada en tono, saturación y luminosidad, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 por color || Resultado en formato SNES, listo para solicitar su copia a CGRAM. Corresponde al buffer de paletas del juego.
|}

=== Indicadores de cada paleta ===

Cada bit de estos indicadores corresponde a una paleta. Las variables <code>BG</code> cubren 0-7 y las <code>SP</code> cubren 8-F.

{| class="wikitable"
! Variables !! Bytes totales !! Bytes por valor !! Qué indican
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> y <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si ya se preparó la base de colores en formato SNES.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> y <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparado el resultado del efecto global.
|}

Estos indicadores evitan repetir conversiones y cálculos que siguen siendo válidos.

=== Preparar una base ===

# Se comprueba si la paleta ya tiene una base registrada.
# Si no la tiene, se obtienen los colores del buffer del juego. Una carga explícita, como <code>TransferPalette</code>, puede proporcionar esa base directamente.
# Se comprueba si el efecto necesita RGB o HSL.
# Si falta esa conversión, se prepara y se marca como disponible.

Si solo cambia el efecto, la base puede seguir siendo válida. Si cambian los colores originales, las llamadas de carga actualizan la base e invalidan las conversiones y resultados que deben calcularse otra vez.

=== Datos de un efecto ===

El ID permite consultar las tablas generadas durante la instalación:

* <code>Types</code>: cálculo que debe realizarse.
* <code>Value1</code>, <code>Value2</code> y <code>Value3</code>: valores de los canales o dirección de la paleta de destino de una transición.
* <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code>: cuánto se aplica cada cambio.

Los canales utilizan valores de 0 a 31. Los ratios van de 0 a 127: 0 conserva el origen y 127 aplica por completo el cambio elegido.

Los cálculos se realizan fuera de NMI. NMI realiza la transferencia de los colores resultantes.

=== Efecto global ===

{| class="wikitable"
! Variable !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selecciona el efecto global. El valor 0 permite restaurar los colores de base.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 0-7 que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 8-F que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Guarda el último ID global procesado por cada paleta.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controla la participación del color fijo y el color 0,0.
|}

Para cada paleta habilitada, el administrador:

# Comprueba si necesita actualizar el resultado del efecto.
# Prepara la base RGB o HSL si todavía falta.
# Calcula el efecto si el resultado anterior ya no sirve.
# Prepara los colores en formato SNES y solicita su transferencia.
# Confirma el ID procesado cuando la carga correspondiente se acepta.

Si se mantiene el mismo efecto y no cambió la base, no hace falta calcularlo otra vez. Al cambiar el ID global se invalidan los resultados anteriores, no necesariamente las bases RGB y HSL.

El ID global 0 también requiere una actualización: el sistema debe cargar de nuevo los colores de base para quitar el efecto anterior.

=== Efecto local y concatenación ===

Un recurso puede tener un efecto propio y recibir también el global. Por ejemplo, un sprite puede cambiar de tono y después oscurecerse junto con el nivel.

El orden es:

# Preparar el resultado del efecto local.
# Utilizarlo como base para el efecto global mediante la llamada de concatenación.
# Calcular el efecto global sobre esa base.
# Cargar el resultado combinado, sin mostrar antes la versión que solo tiene el efecto local.

* La concatenación RGB se utiliza con efectos RGB.
* La concatenación HSL se utiliza con efectos HSL.
* Los recursos que comparten un destino de CGRAM comparten sus colores. Para mostrar dos efectos locales distintos, necesitan destinos que permitan mantener ambos resultados.

=== Si no se acepta la transferencia ===

* Calcular el efecto no significa que ya esté en CGRAM.
* Si la transferencia no se acepta, el administrador puede volver a intentar la actualización.
* Cuando corresponde, se mantiene el resultado anterior utilizable hasta poder sustituirlo.
* No se deben cargar primero los colores originales sin efecto: podrían verse así durante un frame antes del resultado correcto.

== Cómo trabajan juntos ==

El recorrido de un sprite dinámico reúne estas tareas:

# Su lógica elige la pose y la versión de paleta.
# La asignación busca una paleta utilizable y prepara los colores si hace falta.
# La caché protege la pose ya cargada o prepara la carga de una nueva.
# El dibujo escribe los datos de sus piezas en los buffers OAM.
# El administrador de efectos prepara los cambios globales pendientes.
# NMI realiza las transferencias de gráficos y colores solicitadas.

Compartir gráficos, compartir una paleta y compartir una rutina de dibujo son tres cosas distintas. Dynamic Xtreme puede aprovechar cada una sin obligar a que los recursos compartan también las demás.

Dynamic Xtreme internal workings

2026-10-25T21:58:02Z

Anonimzwx: Created page with "{{Select Language|Dynamic_Xtreme_internal_workings}} This article explains how Dynamic Xtreme works, from preparing resources during installation to loading and drawing a pose during gameplay. == What installation prepares == Before a sprite can use its graphics or palette, Dynamic Xtreme must store them in the ROM and prepare the information needed to find them. The same applies to any other dynamic resource you add. The tool reads DynamicInfo, DrawInfo, and Palette..."

{{Select Language|Dynamic_Xtreme_internal_workings}}

This article explains how Dynamic Xtreme works, from preparing resources during installation to loading and drawing a pose during gameplay.

== What installation prepares ==

Before a sprite can use its graphics or palette, Dynamic Xtreme must store them in the ROM and prepare the information needed to find them. The same applies to any other dynamic resource you add.

The tool reads DynamicInfo, DrawInfo, and PaletteEffect files. Each provides a different part: which resources to load, how to draw poses, and which color changes can be applied.

This generates defines in <code>DXDefines.asm</code> that make it easy to use the resources and call the required routines.

=== DynamicInfo: resources and upload data ===

A DynamicInfo brings together the pose graphics, palettes, and general resources needed by a sprite or other code. For dynamic pose graphics, the tool arranges the data in the tile layout expected by the system.

Several properties of each pose are stored in separate tables. All tables use the same order: a pose's entry in one table corresponds to the same pose in the others. In the table below, '''N''' is the number of installed dynamic poses.

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents and purpose
|-
| <code>PoseSize</code> || 2 × N || 2 || Amount of data used by each pose, in bytes. Used to check whether its upload fits within the frame's budget.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Number of 16×16 blocks to allocate in VRAM for the pose. This does not always match the exact byte count copied, since an incomplete tile can still require a block of space.
|-
| <code>PoseResource</code> || 3 × N || 3 || ROM address of each pose's graphics, including the bank, so upload code can locate the full source address.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; two values per pose || Two sizes per pose, corresponding to the two sections its graphics may be split into. The upload routine uses them to place the data correctly in VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || VRAM offset from the start of the first section to the start of the second. Places the second section correctly even if the first ends with an incomplete row.
|}

These tables describe every installed pose, not just those on screen. The cache separately tracks which poses are loaded and where they are stored.

For example, when a requested pose is not yet in VRAM, the system checks how many bytes it needs to upload, finds space for its blocks, then uses its source address and section data to prepare the upload.

==== Palette tables ====

Palettes declared in DynamicInfo files are collected in <code>PaletteTable</code>. If '''P''' is the number of entries across the DynamicInfo palette lists:

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID of each palette.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || ROM address of its colors.
|}

P counts list entries, not just unique palettes: a shared palette may appear in more than one DynamicInfo.

Both lists follow the DynamicInfo palette order. Each DynamicInfo's offset define identifies where its list starts. Selecting a version adds that index to the offset to find both the ID and address of the chosen colors.

The ID identifies a palette so it can be shared; the address allows its colors to be loaded. Neither is the destination palette number: the same installed palette may be assigned to palette 9 or C, for example.

==== General resources and defines ====

Files declared in <code>Resources</code> are stored in ROM. Their address and byte count are available through defines generated in <code>DXDefines.asm</code>. For example, <code>my_resource.bin</code> generates:

* <code>!ResourceMyResource</code>: resource address in ROM.
* <code>!ResourceMyResourceSize</code>: resource byte count.
* <code>!ResourceIDMyResource</code>: resource ID.

Names are normalized to PascalCase: spaces, hyphens, and underscores are removed, and each word starts with a capital letter.

=== DrawInfo: drawing data and routines ===

The DrawInfo describes how a pose is built: its tiles, each tile's position and size, and how the pose changes when flipped.

During installation, Dynamic Xtreme generates drawing routines optimized for the parameters used by the tiles. For example, it considers whether tiles need X and Y offsets, share a size or common properties, and require flipping.

The resulting routine only handles options that the drawing needs. Several poses can share a routine when they need the same handling; this does not mean they also share graphics or IDs.

These tables connect a pose to its drawing data. '''D''' is the number of drawing poses, and '''R''' is the number of generated routines:

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents and purpose
|-
| <code>TableOffset</code> || 2 × D || 2 || Starting offset of the pose's data in its drawing routine's tables. Locates its tiles and offsets without scanning earlier poses.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || Number of tiles in the pose minus one. A four-tile pose stores 3; the routine uses this to loop through its tiles.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Drawing routine used by each pose. Poses with compatible requirements can use the same routine ID.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 per routine || Drawing routine addresses. The routine ID selects the code to run.
|}

Each routine also has the tables its poses need. Here, '''T''' is the number of entries in each of the routine's tables:

{| class="wikitable"
! Data !! Total bytes !! Bytes per value !! Description
|-
| <code>Tiles</code> || T, if generated || 1 || Tile numbers making up the pose.
|-
| <code>Properties</code> || T, if generated || 1 || Each tile's properties, such as flipping and priority relative to the layers.
|-
| <code>XDisplacements</code> and <code>YDisplacements</code> || T per table, if generated || 1 || Each tile's position relative to the pose's origin.
|-
| Flip displacement tables || T per table, if generated || 1 || Positions used when flipping a pose that requires a different layout.
|-
| <code>Sizes</code> || T, if generated || 1 || Each tile's size: 8×8 or 16×16.
|}

Not every routine needs all these tables. If a value is the same for all tiles or can be obtained from a shared value, the tool can generate a routine that uses it directly.

This optimization happens during installation. For example, when all tiles share a size, the routine can use that common value instead of reading a separate size for each tile.

=== PaletteEffect: effect data ===

A PaletteEffect file contains a list of color changes. Installation assigns IDs to them and stores their data in <code>PaletteEffectsTable</code>.

As with pose tables, each effect occupies the same position across the different lists. Effect IDs start at 1; ID 0 means no global effect. In the table, '''E''' is the number of installed effects; together, the tables occupy '''2 + 7 × E bytes'''.

{| class="wikitable"
! Table section !! Total bytes !! Bytes per value !! Contents
|-
| <code>Length</code> || 2 || 2 || Number of installed effects.
|-
| <code>Types</code> || E || 1 || Each effect's type, such as <code>MixH</code>, <code>MixS</code>, or <code>PalTransitionRGB</code>. Selects the calculation to perform.
|-
| <code>Value1</code>, <code>Value2</code>, and <code>Value3</code> || E per table; 3 × E combined || 1 per table || Channel values used by the effect. For transitions, these three bytes store the target palette address instead.
|-
| <code>Ratio1</code>, <code>Ratio2</code>, and <code>Ratio3</code> || E per table; 3 × E combined || 1 per table || How much of the change to apply to each component. Range: 0–127.
|}

For a transition toward another palette, the tool also prepares that palette. It converts the colors to the RGB or HSL format needed by the transition and stores them in ROM. During gameplay, this target can be used without converting it again on every call.

These transition palettes differ from normal palettes uploaded to CGRAM: they contain three components per color and are used to calculate effects.

=== How code finds installed resources ===

<code>DXDefines.asm</code> provides the IDs, addresses, sizes, and offsets resources need. For example, <code>!DynamicPoseIDMySpriteIdle</code> identifies a pose, and <code>!PaletteEffectIDMyEffect0</code> identifies a file's first effect.

Names are normalized to PascalCase: separators such as spaces, hyphens, and underscores are removed, and each word starts with a capital letter. For example, <code>my_sprite</code> becomes <code>MySprite</code>.

Installation also generates <code>BufferTable</code>, which stores the addresses of the blocks containing inserted resources. Each address occupies 3 bytes, followed by a final <code>$FFFFFF</code> value occupying another 3 bytes. For B blocks, the table occupies <code>3 × (B + 1)</code> bytes. The tool uses this information to find the previous installation's data when reinstalling.

Reinstallation may change IDs and addresses. Reinsert any sprites, blocks, and UberASM code that use the generated defines afterward.

== Work performed each frame ==

The main game logic runs the player, sprites, and other code for the current game mode. Code using Dynamic Xtreme requests poses and palettes, prepares local effects, and calls drawing routines. Accepted uploads are added to the transfer lists for NMI.

Once that logic finishes, Dynamic Xtreme's game mode code performs the tasks enabled by the configuration: preparing VRAM updates for Kevin's optimization, maintaining palette state, and calculating pending global effects.

During NMI, Dynamic Xtreme then performs these tasks in order, according to the enabled features:

# Resets <code>DX_Dynamic_CurrentDataSend</code> to 0.
# Increments <code>DX_Timer</code>.
# Increments <code>DX_SyncTimer</code> if the action is not frozen and the game is not paused.
# Performs graphics transfers to VRAM.
# Performs color transfers to CGRAM.
# Updates color 0,0 if the effect system has a pending result.

The following sections therefore follow this order: '''main logic → tasks at the end of the game mode → NMI transfers'''.

=== Main logic ===

Each resource decides what it needs. A sprite may change pose, an animation may request new graphics, or UberASM code may upload a palette or select an effect.

If the requested pose is already loaded, Dynamic Xtreme updates its last-use time to protect it from replacement without uploading its graphics again. Otherwise, it checks the frame's data budget and finds available VRAM space before preparing the upload.

Drawing is also prepared here: routines write the positions, tiles, and properties of the pieces to display into the OAM buffers.

A request can fail, for example because its data would exceed the remaining budget. The requesting code must check the result and decide whether to keep the previous state or retry later. A rejected upload is not automatically saved for another frame.

=== Game mode tasks ===

This stage performs the following tasks, according to the enabled features.

'''Before game logic runs:'''

# If <code>ControllerOptimization</code> is enabled, the controller routine runs here instead of during NMI.
# Checks whether Dynamic Xtreme should run in the current game mode. If not, its variables are reset. This happens every frame spent in a disallowed mode.

The normal game logic then runs, including sprites and code requesting uploads or palette changes.

'''After that logic finishes:'''

# If Kevin's VRAM optimization is enabled, Lunar Magic's update destinations are adjusted before the transfers take place.
# Palette update flags are cleared to 0, and protection timers greater than 0 are decremented. This is skipped while paused and in disallowed modes.
# Applies global effects to palettes that need an update and prepares their color transfers. This is also skipped if the previous check prevents further processing.

VRAM and CGRAM transfers happen later, during NMI. This stage prepares what will be copied.

=== Allowed game modes ===

Dynamic Xtreme uses two game mode checks:

* '''General system:''' <code>Routines_AllowedGameMode</code>, exposed as <code>!AllowedGameMode</code>. Determines whether the system is reset, its NMI runs, and palette tasks are performed. Palette assignment macros also use this check when processing an upload from a DynamicInfo.
* '''Sprite routines:''' <code>DXAllowedGameMode</code> uses a separate table. <code>!Upload</code> and its general macros use a table with the same values to decide whether to process a new request.

Enabling the general system therefore does not mean every sprite function accepts new uploads in that mode. This table shows the current checks; IDs are hexadecimal:

{| class="wikitable"
! Game mode !! SMW screen or stage !! General system !! DXAllowedGameMode / new Upload requests
|-
| <code>$06</code> || Title screen spotlight opening. || Yes || No
|-
| <code>$07</code> || Title screen. || Yes || Yes
|-
| <code>$08</code> || File select. || Yes || No
|-
| <code>$09</code> || File erase. || Yes || No
|-
| <code>$0A</code> || One- or two-player selection. || Yes || No
|-
| <code>$0C</code> || Overworld loading. || Yes || No
|-
| <code>$0D</code> || Overworld fade-in. || Yes || No
|-
| <code>$0E</code> || Overworld. || Yes || Yes
|-
| <code>$12</code> || Level preparation. || Yes || No
|-
| <code>$13</code> || Level fade-in. || Yes || No
|-
| <code>$14</code> || In-level gameplay. || Yes || Yes
|-
| <code>$15</code> || Fade-out to Game Over / Time Up. || Yes || No
|-
| <code>$1B</code> || Castle cutscene or credits. || No || Yes
|-
| <code>$1C</code> || Fade-out to Yoshi's House in the credits. || Yes || No
|-
| <code>$1D</code> || Loading Yoshi's House in the credits. || Yes || No
|-
| <code>$1E</code> || Yoshi's House fade-in during the credits. || Yes || No
|-
| <code>$1F</code> || Yoshi's House in the credits. || Yes || Yes
|-
| <code>$24</code> || Enemy roll fade-in. || Yes || No
|-
| <code>$25</code> || Credits enemy roll. || Yes || Yes
|-
| <code>$29</code> || The End screen. || No || Yes
|-
| Other values from <code>$00</code> to <code>$2F</code>. || — || No || No
|}

Stage names follow the [https://github.com/IsoFrieze/SMWDisX/blob/master/bank_00.asm SMW game modes documented in SMWDisX]; permissions come from Dynamic Xtreme's tables.

When <code>Upload</code> does not allow a new request, it checks whether the resource has a previous pose. If so, it updates that pose's last-use time and returns carry set; otherwise, it returns carry clear. It does not request another pose on this path.

Modes <code>$1B</code> and <code>$29</code> show why the columns must be read separately: passing the sprite check does not enable the general system's NMI or prevent the game mode code from resetting its variables. The sprite column alone does not guarantee full operation in those modes.

=== Transfers during NMI ===

NMI is an interrupt the SNES can generate at the start of VBlank, after drawing the visible part of the screen. The game uses this interval to update graphics, colors, and other video data.

In allowed modes, Dynamic Xtreme performs these tasks in order, according to the enabled features:

# Resets <code>DX_Dynamic_CurrentDataSend</code> to 0 to count requests from the next logic cycle. Transfers already prepared remain in their lists.
# Increments <code>DX_Timer</code>.
# Checks <code>$9D</code> and <code>$13D4|!addr</code>. If both are 0, increments <code>DX_SyncTimer</code>.
# Performs pending VRAM transfers if <code>GraphicsChange</code> is enabled.
# Performs pending CGRAM transfers if <code>PalettesChange</code> is enabled.
# If <code>PalettesEffects</code> is enabled, updates color 0,0 when a result is pending.

The copies use DMA. NMI reads each request from the lists, sets the source address, byte count, and destination, then starts the transfer.

VBlank time is limited, and SMW also needs it for its own screen updates. To limit data sent in one frame and prevent flickering, Dynamic Xtreme uses <code>DX_Dynamic_CurrentDataSend</code> to count requested bytes and <code>DX_Dynamic_MaxDataPerFrame</code> to set the limit. Before accepting a normal upload, it checks whether the additional bytes would exceed that limit.

==== Transfer lists ====

Each request stores the source address and bank, byte count, and VRAM or CGRAM destination.

NMI processes the lists from the last entry to the first, then empties them. This does not erase the uploaded graphics or colors: they stay at their destinations until other code changes them.

The VRAM list uses 0 when empty. The CGRAM list uses <code>$FF</code> because it stores the last entry's index rather than the entry count directly.

Code writing to the same destination must coordinate its uploads. Request order does not replace deciding which resource may use each region.

Resources are normally read from ROM. If a resource is in a RAM buffer, you must keep its contents unchanged until NMI performs the transfer. For example, a palette prepared in RAM must not be modified or its buffer reused before the copy. The list stores the address, not a copy of the data; Dynamic Xtreme does not protect the buffer from changes made by other code.

==== Data budget ====

Transfer macros such as <code>%TransferToVRAM()</code> and <code>%TransferToCGRAM()</code> check the requested byte count in <code>DX_Dynamic_CurrentDataSend</code>. If the new upload would exceed <code>DX_Dynamic_MaxDataPerFrame</code>, it is rejected. Accepted uploads add their bytes to the counter.

The default limit is <code>$0800</code>, or 2048 bytes. It helps prevent flickering caused by sending too much data in a frame. It limits data volume, rather than measuring the exact time each transfer takes.

Variants such as <code>%ForcedTransferToVRAM()</code> and <code>%ForcedTransferToCGRAM()</code> accept uploads without checking the limit. Their bytes still count toward <code>DX_Dynamic_CurrentDataSend</code>, leaving less room for later normal uploads. They are used for priority uploads, such as the player's graphics; they do not prevent flickering if too much data is requested.

See [[Dynamic_Xtreme_ASM_API#PPU|PPU in the ASM API]] for the difference between byte budget and list capacity, transfer restrictions, and the checks your code must perform.

==== The two timers ====

'''DX_Timer: protecting requests'''

<code>DX_Timer</code> advances when Dynamic Xtreme's NMI code runs. Besides measuring how long a pose has gone unused, it prevents a resource from repeating requests before its previous ones have been processed.

A logic cycle does not always correspond to a full NMI execution. During slowdown, SMW may run a shortened NMI, allowing two logic cycles to occur without Dynamic Xtreme's transfer lists being processed between them.

Without protection, a resource could add its uploads to those lists again. Duplicate requests would take more space and could cause flickering.

To prevent this, sprite pose upload routines compare <code>DX_Timer</code> with a two-byte value stored by the sprite, usually called <code>SafeFrame</code>. The sprite aliases use <code>!SafeFrameLowByte,x</code> and <code>!SafeFrameHighByte,x</code>.

The process is:

# '''Compare the timers.''' If <code>SafeFrame</code> equals <code>DX_Timer</code>, that sprite has already processed its pose upload at this timer value. The routine skips a new request.
# '''Record the attempt before processing it.''' If the values differ, it copies <code>DX_Timer</code> to <code>SafeFrame</code>, then checks whether it can reuse the pose or must request another.
# '''Check the result.''' A new pose request can succeed or fail. Even if it fails, the value saved in <code>SafeFrame</code> is not undone.

<code>SafeFrame</code> therefore records '''when the last attempt was processed''', not when a pose was successfully loaded. If an upload fails, calling the routine again with the same <code>DX_Timer</code> does not allow another attempt, even if the desired pose or available space has changed.

In <code>!Upload</code> and <code>!UploadWithoutPoseOffset</code>, rejected requests and calls skipped by this protection use the same fallback:

* If <code>!LastPoseHashIndex,x</code> is not <code>$FF</code>, they update that pose's last-use time to protect it from replacement and return carry set. The sprite can keep drawing the last available pose.
* If it is <code>$FF</code>, no fallback pose exists and they return carry clear.

For example, this can happen during slowdown:

# <code>DX_Timer = $0030</code>. The sprite saves <code>$0030</code> in its <code>SafeFrame</code> and tries to obtain a new pose. No data budget remains, so the request fails; it keeps the previous pose if one exists.
# SMW runs another logic cycle without processing Dynamic Xtreme's NMI. The timer is still <code>$0030</code>. The same sprite's next call detects the match and does not repeat the request.
# When Dynamic Xtreme's NMI runs, <code>DX_Timer</code> advances to <code>$0031</code>. On the next call, the timers no longer match and the sprite can retry. A rejected request does not retry itself: the sprite code must call the routine again.

Sprite pose upload aliases enable this protection. In [[Dynamic_Xtreme_ASM_API#GeneralUpload|GeneralUpload]] and [[Dynamic_Xtreme_ASM_API#Upload_(general_macro)|Upload (general macro)]], <code>safeCheck</code> controls it; <code>checkLast</code> separately controls fallback to the previous pose. [[Dynamic_Xtreme_ASM_API#TakeDynamicRequest|TakeDynamicRequest]] and [[Dynamic_Xtreme_ASM_API#PPU|PPU transfer macros]] do not perform this <code>SafeFrame</code> check for you.

<code>DX_Timer</code> continues advancing while paused whenever this part of NMI runs.

'''DX_SyncTimer: synchronized animations'''

The main purpose of <code>DX_SyncTimer</code> is to give sprites a shared animation clock. For example, sprites using the same poses can use it to select a pose every four frames.

They then change together and request the same pose. The first request may need to upload it; later requests reuse it without scheduling another graphics upload. This saves DMA transfers and data per frame.

With independent timers, sprites could use different poses from the same animation at once, requiring more uploads and VRAM space.

<code>DX_SyncTimer</code> stops while paused or while the action is frozen, so synchronized animations stop too.

== Graphics uploads: GraphicsChange ==

<code>GraphicsChange</code> stores a list of upload requests in RAM. During NMI, those requests are processed and their data is copied to VRAM.

=== List variables ===

Here, '''V''' is <code>!VRAMTransferSize</code>, which defaults to 64. Each of the four request tables allocates V bytes; with 2-byte entries, that allows 32 requests. Together with the counter, they occupy <code>1 + 4 × V</code> bytes: 257 by default.

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Number of pending requests. 0 means the list is empty.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 by default || 2 || Each request's source address, excluding the bank.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 by default || 2 allocated; 1-byte bank || Source bank.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 by default || 2 || Number of bytes to copy.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 by default || 2 || VRAM destination address.
|}

Tables use the same order: the first entry of each table belongs to the first request, the second to the second request, and so on. Each entry occupies 2 bytes, so offsets advance through <code>$00</code>, <code>$02</code>, <code>$04</code>, and so on.

These names represent RAM addresses calculated in <code>DXDefines.asm</code>. Addresses can change with the configuration and enabled features.

=== Adding a request ===

<code>%TransferToVRAM()</code> performs these steps:

# Calculates the total byte count if the new upload is added to <code>DX_Dynamic_CurrentDataSend</code>.
# Compares it with <code>DX_Dynamic_MaxDataPerFrame</code>. If it exceeds the limit, returns carry clear without adding the request.
# Uses <code>DX_PPU_VRAM_Transfer_Length</code> to find the next entry and increments that counter.
# Stores the source, bank, byte count, and destination in the tables.
# Updates <code>DX_Dynamic_CurrentDataSend</code> with the upload's byte count and returns carry set.

<code>%ForcedTransferToVRAM()</code> stores the same information without checking the byte limit. <code>FromAddr</code> and <code>Resource</code> variants make it easier to get the source from a full address or resource defines.

Adding a request does not copy graphics immediately: it prepares the information for NMI.

=== Processing requests during NMI ===

The <code>VRAMDMA</code> routine:

# Reads <code>DX_PPU_VRAM_Transfer_Length</code>. If it is 0, returns because there are no requests.
# Calculates the last entry's offset: <code>(Length - 1) × 2</code>.
# Reads its source, bank, and byte count into the DMA registers.
# Writes the VRAM destination to <code>$2116-$2117</code> and starts the transfer through <code>$420B</code>.
# Moves back 2 bytes to process the previous request, repeating until the first is complete.
# Writes 0 to <code>DX_PPU_VRAM_Transfer_Length</code> to mark the list as empty.

'''The list runs from last to first.''' There is no need to clear every stored value afterward: with the length at 0, the next request reuses the first entry.

=== Animations with a fixed destination ===

Animation code must:

# Select the image for the current animation step.
# Calculate its source address.
# Request a transfer to the animation's VRAM destination.
# Check carry. If the upload is rejected, keep the previous image and retry.

The destination can stay the same. Only the image copied there changes; the transfer list does not decide when the animation advances.

See [[Dynamic_Xtreme_UberASM_guide#Creating_graphics_animations|Creating graphics animations in the UberASM guide]] for complete code.

=== Loading a dynamic pose ===

Pose loading uses the cache to avoid uploading graphics that are already available:

# Looks for the ID in the hash table.
# If already registered, updates its last-use time without adding another upload.
# Otherwise, checks the byte count and finds suitable space in the VRAM map.
# Selects poses that can be replaced, considering their time since last use and the new pose's space requirements.
# Updates the cache tables and map.
# <code>DynamicRoutine</code> splits the pose's data into the required transfers.
# NMI performs those transfers.

[[#Dynamic_sprites:_DynamicPoses|Dynamic sprites: DynamicPoses]] covers each step, including hash lookup, the map, replacement policy, and splitting uploads into rows.

== Palette uploads and assignment: PalettesChange ==

The system distinguishes two values:

* '''Palette ID:''' identifies colors stored in ROM.
* '''Destination color:''' specifies the starting color in CGRAM for the uploaded colors. For example, <code>$91</code> starts at color 1 of palette 9.

Automatic assignment lets sprites share colors without requiring a fixed destination for each sprite.

=== CGRAM upload list ===

Here, '''C''' is <code>!CGRAMTransferSize</code>, which defaults to 64. The tables and counter allocate <code>1 + 7 × C</code> bytes, or 449 by default. Although <code>SourceBNK</code> allocates 2 × C bytes, the code uses one bank byte per request.

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Last pending request's index. <code>$FF</code> means the list is empty; 0 means one request.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 by default || 2 || Source address, excluding the bank.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 allocated by default || 1 used per request || Source bank.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 by default || 2 || Number of bytes to copy. Each color occupies 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 by default || 1 || First destination color in CGRAM.
|}

During NMI, <code>CGRAMDMA</code>:

# Starts at the last pending request.
# Configures DMA with that request's source and byte count.
# Selects the first color through <code>$2121</code> and performs the copy.
# Continues with earlier requests.
# Writes <code>$FF</code> to <code>DX_PPU_CGRAM_Transfer_Length</code> when finished.

<code>TransferPalette</code> macros also update the color copies and effect state:

* '''Without the global effect:''' request the upload and update SMW's buffers, preventing the game from reusing old colors during the goal victory animation.
* '''With the global effect:''' store the original colors and prepare the state needed to apply the effect before sending them to CGRAM.

=== Automatic assignment ===

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Purpose
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || ID assigned to each destination. <code>$FFFF</code> marks a free entry; <code>$FFFE</code> marks one set aside.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protects each destination from automatic replacement while in use.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; one bit per sprite palette || Tracks sprite palettes assigned with the global effect enabled. Sharing an assignment also requires this setting to match.
|}

The search follows this order:

# Reuse an assignment with the same ID and compatible effect setting.
# If none exists, use a free entry.
# If none is free, replace an entry that is not set aside and whose timer is 0.
# If no entry qualifies, report assignment failure.

While using the palette, the resource keeps its timer at 2. Reaching 0 does not erase the colors: the assignment can still be reused if another resource has not replaced it.

=== Manual assignment and version ===

* '''Manual with upload:''' code selects the destination and requests its colors.
* '''Manual without upload:''' code selects the destination and uses the colors already available there.
* '''Version:''' selects an entry in the DynamicInfo palette list. The last processed version lets the system check whether that selection changed.

Resources choosing the same destination with different colors must coordinate their uploads. Keeping a palette protected does not mean uploading its colors again.

== Pose drawing: DrawingSystem ==

Drawing prepares a pose's pieces in OAM: the tiles to display, their positions, and their properties. The graphics data must be in VRAM.

=== Drawing steps ===

# Finds the pose's routine and data through <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code>, and <code>TableOffset</code>.
# Gets the tile count from <code>NumberOfTilesMinus1</code>.
# Calculates each tile's position from the sprite position, displacements, and applicable flips.
# Checks whether the tile is visible and OAM space remains.
# Writes its position, tile number, properties, and size to the OAM buffers.

The tile number depends on the drawing type:

{| class="wikitable"
! Case !! How the tile is selected
|-
| Dynamic pose || Adjusted to the graphics' location in VRAM.
|-
| Static pose || Uses its fixed tile number.
|-
| Pose using a shared tile || Code must set <code>!Tile</code> before drawing.
|}

=== Priority and available space ===

* In '''LoROM''', the system tracks available OAM entries itself.
* In '''SA-1''', it integrates with MaxTile.
* '''Drawing priority''' orders sprite tiles. It is separate from the property that places a tile in front of or behind layers.
* SNES '''per-scanline limits''' still apply. Loading a pose does not guarantee that all its tiles can be displayed.

== Player and Yoshi ==

=== PlayerFeatures ===

The original player has its own routines to select and upload pose pieces. <code>PlayerFeatures</code> integrates that work with Dynamic Xtreme uploads and lets you change the graphics and palette sources.

With the original format, the game still selects the pose pieces. The routine gets their addresses from the configured source and compares them with the previous addresses to upload only those that changed.

These uploads use forced transfers, and their bytes also count toward later normal requests. They retain priority while remaining part of the system's data budget.

The player's palette receives special handling: it combines the game's own colors and selections with the custom source. It is more involved than replacing an ordinary sprite's entire palette.

Support for custom players lets other systems handle their poses and drawing differently. It does not automatically convert any spritesheet to the original player's format.

=== YoshiFeatures ===

Yoshi also uploads graphics in pieces. <code>YoshiFeatures</code> lets you change their source while retaining the layout expected by the routines.

The code calculates which pieces are needed and prepares uploads to the corresponding VRAM destinations. Like the player's uploads, these receive priority handling.

This option requires <code>PlayerFeatures</code> and shares its compatibility restrictions. Enabling Yoshi's features alone does not avoid a conflict with the player system.

== Memory and optimizations ==

=== Free7E2000 ===

SMW keeps original player, Yoshi, and some animation graphics in RAM. In ROMs without SA-1, this option adapts uploads to read that data from ROM instead.

Dynamic Xtreme uses the recovered RAM for its internal variables. It is not free space for other code to overwrite.

SA-1 uses different addresses and disables this option. See the ranges in [[Dynamic_Xtreme#RAM_usage|RAM usage]].

=== ControllerOptimization ===

This option moves controller processing from NMI to the game mode code. It frees time for screen updates without adding a frame of input delay or changing which buttons the game receives.

=== FixedColorOptimization ===

The console uses the fixed color for color math. To update it, the game prepares its components and sends them to the corresponding register.

This optimization replaces that preparation with a shorter sequence. The color is still sent to the console, with less work required during NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic uses lists called stripe images to update parts of the tilemaps. These contain both the data and destination information.

The integrated version of Kevin's optimization prepares part of the destination adjustment outside NMI, leaving less setup work for transfer time.

This option replaces the standalone original patch. It must not be uninstalled after installation; keep this in mind before enabling it.

=== StatusBarOptimization ===

The original status bar updates specific VRAM regions. This option prepares its transfers more directly, reducing the DMA setup needed during NMI.

It modifies updates to the original status bar rather than adding a new one. As a result, it conflicts with resources that replace, modify, or remove that bar.

== Dynamic sprites: DynamicPoses ==

The system works as a '''pose cache in VRAM'''. Instead of keeping a graphics copy for each sprite, it stores a pose that every resource needing it can reuse.

* A pose is uploaded only once while it remains in the cache.
* Later requests update its last-use time without adding another graphics upload.
* A pose is not erased when a resource stops using it. It stays until its space is needed and it is selected for replacement.
* If replaced and later requested again, it must be uploaded again.

Replacement depends on '''time since last use''', not time since upload, as well as whether the space fits the new pose.

=== Three different values ===

{| class="wikitable"
! Value !! What it identifies
|-
| Pose ID || The installed pose. A 16-bit value used to look up its data in ROM.
|-
| Hash table index || The RAM entry that records the pose. Ranges from 0 to 127.
|-
| VRAM block || ID of one of the 128 16×16 tile positions in sprite VRAM. Numbered left to right and top to bottom, from 0 to 127. A pose occupying several blocks stores its first block's ID.
|}

The hash table index and VRAM block do not need to match. A table entry can record a pose starting at any allowed block.

=== Registered pose tables ===

{| class="wikitable"
! Variable or table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Number of registered poses.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Number of registered poses for each hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || Full pose ID in each entry. <code>$FFFF</code> marks a free entry.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Starting VRAM block of each pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || <code>DX_Timer</code> value at the pose's last use.
|}

These tables occupy '''769 bytes''' of RAM. They track poses registered during gameplay, whereas the DynamicInfo-generated tables describe every installed pose.

=== Looking up a pose ===

<code>DynamicPoseHashmap_FindPose</code> uses a 128-entry hash table. The hash selects where to start searching:

<pre>
hash = pose ID AND $007F
</pre>

Different IDs can share a hash. For example, <code>$0005</code> and <code>$0085</code> both produce <code>$05</code>. The hash alone therefore cannot confirm that a pose is loaded; the full ID must also match.

The search follows these steps:

# Saves the requested ID and calculates its hash.
# If <code>DX_Dynamic_Pose_Length</code> is 0, no poses are registered and the search ends.
# Checks <code>DX_Dynamic_Pose_HashSize[hash]</code>. If it is 0, no registered pose has that hash, so the search also ends.
# Starts at the entry whose index matches the hash.
# Reads that entry's ID. If it matches the requested ID, the pose has been found.
# Otherwise, continues to the next entry in the search sequence.

The sequence advances '''15 entries per attempt''', wrapping around after 127:

<pre>
next index = (current index + 15) AND $7F
</pre>

With 128 entries, this step visits every position before repeating one. For hash <code>$05</code>, the sequence starts:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

==== The pose count for each hash ====

Each hash has its own counter in <code>DX_Dynamic_Pose_HashSize</code>. For example, if two registered poses have IDs that produce hash <code>$05</code>, <code>DX_Dynamic_Pose_HashSize+$05</code> contains 2.

This number tells the search '''how many poses have that hash''', not how many positions to visit. The search uses a temporary copy of the counter:

# Starts with the registered pose count for the requested hash.
# Visits positions in the sequence until it finds the requested ID or has checked that many poses with the same hash.
# Each time it finds a pose with the same hash but a different ID, decrements the temporary counter.
# Free positions and poses with other hashes do not decrement it; the search continues.
# If the temporary counter reaches 0 without finding the ID, the requested pose is not registered and the search ends.

The counter in <code>DX_Dynamic_Pose_HashSize</code> does not change during lookup. It changes only when poses are added to or removed from the cache.

For example, suppose the requested ID is <code>$0105</code>, which produces hash <code>$05</code>, and that hash's counter is 2:

{| class="wikitable"
! Visited position !! Stored ID !! ID's hash !! Hash $05 poses still to check
|-
| <code>$05</code> || <code>$0005</code> || <code>$05</code> || 1: same hash, but a different ID.
|-
| <code>$14</code> || <code>$0014</code> || <code>$14</code> || 1: different hash, so the counter is unchanged.
|-
| <code>$23</code> || <code>$0085</code> || <code>$05</code> || 0: both poses with this hash have been checked. <code>$0105</code> is not registered.
|}

Usually, each hash has one or two poses. This allows lookup with few comparisons and a typical cost close to <code>O(1)</code>. It does not mean only one or two positions are always visited: entries with other hashes may lie between them. Many collisions can make the search longer.

'''A free entry does not end the search.''' It may have been emptied by replacing a pose, with another pose of the same hash still farther along the sequence. The counter tells the search when all poses with that hash have been checked, even with gaps between them.

==== When the pose is found ====

<code>TakeDynamicRequest</code>:

# Gets the matching entry's index.
# Writes the current <code>DX_Timer</code> value to that entry's <code>DX_Dynamic_Pose_TimeLastUse</code>.
# Reports request success without scheduling another graphics upload.

All resources requesting that ID therefore use the same pose and keep it protected. They may be normal, cluster, or extended sprites, or any other code using the system.

This also prevents duplicate uploads within one cycle: once the first request is accepted, the pose is registered even though the actual transfer will occur during NMI.

=== When the pose is not registered ===

<code>TakeDynamicRequest</code> proceeds with a new upload:

# Reads <code>PoseSize</code> and calculates <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# If the result exceeds <code>DX_Dynamic_MaxDataPerFrame</code>, returns failure without changing existing poses.
# Reads <code>Pose16x16Blocks</code> to find the required block count.
# Calls <code>VRAMMap_GetBestSlot</code> to find suitable space.
# If no usable space exists, returns failure.
# Removes poses occupying the chosen space from the map and hash table.
# Finds a free hash table entry and registers the new pose.
# Updates the VRAM map and frame data counter.
# Calls <code>DynamicRoutine</code> to add the transfers.

The budget check happens before replacing poses. If the new upload cannot fit in the frame, no space is freed for a request that cannot be fulfilled.

==== Adding and removing hash table entries ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> looks for an entry whose ID is <code>$FFFF</code>, using the same sequence of 15-entry steps.
* <code>DynamicPoseHashmap_Add</code> stores the ID and last-use time, increments <code>DX_Dynamic_Pose_Length</code>, and increments the corresponding hash counter.
* <code>DynamicPoseHashmap_Remove</code> writes <code>$FFFF</code> to the removed ID and decrements both counters.

Removing an entry does not itself erase VRAM pixels. It marks the pose as unavailable in the cache; the new transfers overwrite the chosen space.

=== Representing the VRAM map ===

The map represents '''128 16×16 tile positions in sprite VRAM''', numbered left to right and top to bottom. Each block is one of those positions, not a contiguous 128-byte range.

A 16×16 tile consists of four 8×8 tiles arranged in two rows. The map manages the positions occupied by a pose; <code>DynamicRoutine</code> later handles how its data must be distributed for upload.

{| class="wikitable"
! Table !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Section's starting position. Bit <code>$80</code> marks it as restricted: dynamic poses cannot use this space.
|-
| <code>DX_Dynamic_Tile_Size</code>, also called <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || If bit <code>$80</code> is set, the remaining bits hold the section's position count minus one. Otherwise, they hold the occupying pose's hash index. Check <code>Offset</code> to determine whether the space is restricted.
|}

These two tables occupy '''256 bytes'''. Together with the pose tables, the manager uses '''1025 bytes''' of RAM, excluding transfer lists and working scratch memory.

=== Map sections ===

A section groups consecutive map positions that are restricted, free, or occupied by one pose. Its information is stored at '''the first and last positions''', allowing traversal to jump to the previous section without checking every position in between.

The following examples show three possible states for a 6-position section from <code>$20</code> to <code>$25</code>. These are alternatives, not three sections occupying the same space at once.

==== Example 1: restricted section ====

{| class="wikitable"
! Table entries !! Value !! Meaning
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> and <code>+$25</code> || <code>$A0</code> || <code>$80</code> marks the restriction; <code>$20</code> identifies the start.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> and <code>+$25</code> || <code>$85</code> || The section has 6 positions: <code>($85 AND $7F) + 1 = 6</code>.
|}

Although the high bit of <code>Size</code> is set, '''this space is not free for dynamic poses''': the restriction bit in <code>Offset</code> excludes it. It is not evaluated as a replaceable pose.

<code>DynamicPoseSpaceConfig</code> uses this section type to exclude parts of SP1–SP4 that dynamic sprites must not use.

==== Example 2: free section ====

{| class="wikitable"
! Table entries !! Value !! Meaning
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> and <code>+$25</code> || <code>$20</code> || Starts at <code>$20</code> and is not restricted.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> and <code>+$25</code> || <code>$85</code> || Bit <code>$80</code> marks a free section's size: <code>$05 + 1 = 6</code> positions.
|}

This section is available. It can hold a pose needing up to 6 positions; placing a 4-position pose leaves the other 2 as a separate free section.

==== Example 3: section occupied by a pose ====

Suppose a 6-block pose is registered at hash entry <code>$07</code> and occupies positions <code>$20</code> through <code>$25</code>:

{| class="wikitable"
! Table entries !! Value !! Meaning
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> and <code>+$25</code> || <code>$20</code> || The section starts at <code>$20</code> and is not restricted.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> and <code>+$25</code> || <code>$07</code> || Bit <code>$80</code> is clear: <code>$07</code> is the pose's hash index, not its block count.
|}

To find the position count and time since last use:

# Read the pose ID at <code>DX_Dynamic_Pose_ID+$0E</code>. The offset is <code>$0E</code> because each ID occupies 2 bytes and <code>$07 × 2 = $0E</code>.
# Use that ID to read <code>Pose16x16Blocks</code>, which contains 6 in this example.
# Read <code>DX_Dynamic_Pose_TimeLastUse+$0E</code> to calculate how long the pose has gone unused.

<code>DX_Dynamic_Pose_Offset+$07</code> stores <code>$20</code>, connecting the registered pose to its VRAM position.

=== Traversal and space search ===

<code>VRAMMap_GetBestSlot</code> starts at 16×16 tile position <code>$7F</code>. To traverse the map:

# Reads <code>DX_Dynamic_Tile_Offset</code> at the current position.
# Gets the section's start with <code>Offset AND $7F</code>.
# Evaluates that section and spaces it can form with adjacent sections.
# Moves to <code>section start - 1</code>, the previous section's last position.
# Repeats until reaching the beginning of the map.

For example, if the last sections start at <code>$70</code>, <code>$60</code>, and <code>$50</code>:

{| class="wikitable"
! Visited position !! Start read from Offset !! Next position
|-
| <code>$7F</code> || <code>$70</code> || <code>$6F</code>
|-
| <code>$6F</code> || <code>$60</code> || <code>$5F</code>
|-
| <code>$5F</code> || <code>$50</code> || <code>$4F</code>
|}

This traverses '''whole sections''', not every tile in between.

==== What the traversal evaluates ====

A candidate space can consist of '''one section or several adjacent sections'''. At each step, the search checks:

* A restricted section cannot be used, and sections cannot be combined across it.
* A pose protected by recent use cannot be part of the space either.
* If the candidate is still too small, an adjacent section can be added to reach the required block count.
* Once the pose fits, the candidate is compared with the best one found: first by its time-since-last-use score, then by the smallest sufficient space.

A section is not chosen merely because it contains the longest-unused pose. The '''whole space''' must fit the new pose. When combining sections, the score depends on the most recently used pose within that space.

The search keeps these temporary values:

{| class="wikitable"
! Working data !! Total bytes !! Bytes per value !! Purpose
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 per field || Start, score, and block count of the current candidate.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 per field || Same fields for the best candidate found.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Block count needed by the new pose.
|}

These names refer to working scratch memory, not additional persistent RAM.

=== Replacement policy: time since last use and enough space ===

The system does not simply choose the first pose uploaded. It uses the time since the pose's '''last use''':

<pre>
time since last use = DX_Timer - pose TimeLastUse
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> gets each region's size and score:

{| class="wikitable"
! Case !! Score and handling
|-
| Free region || <code>$FF</code>. Preferred over occupied regions.
|-
| Occupied region || Time since last use, capped at <code>$FE</code>.
|-
| Unused for 0 or 1 timer increments || Cannot be replaced: the pose is still protected.
|-
| Restricted region || Excluded: dynamic poses cannot use this space.
|}

Protection requires '''at least two increments of <code>DX_Timer</code> without using the pose''' before it can be replaced. Each resource requesting it again updates its last-use time and protects it again.

==== Why the longest-unused pose is not always replaced ====

The new pose needs enough contiguous space. A small space alone is not useful, even if it has gone unused for a long time.

For example, consider a new pose needing 4 blocks:

{| class="wikitable"
! Candidate space !! Time since last use !! Suitable?
|-
| Pose A: 2 blocks, with no usable adjacent space || 20 || No: frees only 2 blocks.
|-
| Pose B: 4 blocks || 8 || Yes: fits the new pose.
|}

Here, B can be replaced while A stays. A has gone unused longer, but its space cannot satisfy the request.

If two or more adjacent regions can be replaced, the system can consider them together. It then:

* Adds their block counts.
* Uses the '''lowest score''' among them: the shortest time since last use.
* Excludes any restricted or protected region from the combined space.

This prevents a recently used pose from being overwritten just because it is next to a long-unused one.

==== Choosing among valid candidates ====

# The candidate must have at least the requested block count.
# The highest score wins: free space or the longest time since last use.
# If scores match, the smaller candidate wins, provided the pose fits.
# If score and size both match, the previously chosen candidate is kept.

Regions are combined during the search when the candidate is still too small. The system does not combine every replaceable region regardless of the requested size.

=== Replacing and splitting the chosen region ===

Once the space is chosen:

# <code>VRAMMap_RemovePosesInSpace</code> traverses its regions and removes poses being replaced from the hash table.
# <code>VRAMMap_RemoveSpace</code> marks the chosen space as one free region by updating its endpoints.
# A free hash entry is found, and the starting block is stored in <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registers the pose.
# <code>VRAMMap_AddPoseInSpace</code> writes the pose's hash index and region start at the first and last blocks.
# Any leftover blocks become another free region.

If a 6-block region holds a 4-block pose, it becomes a 4-block occupied region and a 2-block free region. Other poses are not moved to compact VRAM.

=== DynamicRoutine: preparing pose transfers ===

At this point, space has been chosen and the pose registered. <code>DynamicRoutine</code> turns that allocation into transfer requests.

It uses these values:

{| class="wikitable"
! Data !! Amount read per pose !! Purpose
|-
| Starting block || 1 byte || Position chosen by the VRAM map.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes from a 256-byte table || Converts one of the 128 blocks to a VRAM offset.
|-
| <code>PoseResource</code> || 3 bytes || Full ROM address of the pose data.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: two 2-byte values || Byte counts of the first and second sections.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || VRAM offset for the second section.
|}

==== Converting the block to a VRAM address ====

A 16×16 block does not convert to a simple linear byte offset. Each block uses 8×8 tiles distributed across VRAM rows.

<code>OffsetToVRAMOffset</code> accounts for that layout. For example:

{| class="wikitable"
! Block !! Offset !! VRAM address
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

These VRAM addresses are measured in 2-byte words, not bytes. The routine adds the <code>$6000</code> base used for sprite graphics.

==== Processing sections and rows ====

# Gets the source from <code>PoseResource</code>.
# Processes the first section's bytes through <code>DynamicRoutineLine</code>.
# If the second section's size is 0, returns.
# Otherwise, advances the source by the first section's byte count.
# Adds <code>PoseSecondLineOffset</code> to the VRAM offset and processes the second section.

<code>DynamicRoutineLine</code> splits each section according to its rows and starting position. For destination V measured in VRAM words, it prepares:

<pre>
First row end = (V + $0100) AND $FF00
Bytes to that end = (first row end - V) × 2
Second part destination = first row end + $0100
Second part bytes in a group = $0200 - first part bytes
</pre>

Sizes are byte counts, while VRAM destinations are word addresses. This is why the calculation multiplies by 2 to find how many bytes fit before the end of a row.

The routine uses three paths:

* <code>.EndLine</code>: adds one final request for the remaining bytes.
* <code>.TwoLinesWithEndLine</code>: adds two requests for the remaining data, each with its own destination and byte count.
* <code>.TwoLines</code>: adds two requests totaling <code>$0200</code> bytes, advances the source and destinations, and repeats for the remaining data.

A direct path precedes the general loop: if the destination starts on a <code>$0100</code>-word boundary and the section contains at least <code>$0200</code> bytes, the routine uses <code>.EndLine</code> to prepare the entire section as one request.

For example, a <code>$0200</code>-byte section starting at <code>$6020</code> is split as follows:

{| class="wikitable"
! Request !! Source !! VRAM destination !! Bytes
|-
| First || Section start || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Second || Section start + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Together, the two requests copy the section's 512 bytes to the destinations calculated from the row layout. They are not two complete copies of the pose.

Each request uses these tables:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Each added request increments <code>DX_PPU_VRAM_Transfer_Length</code>.

The pose's total byte count was already checked and added to <code>DX_Dynamic_CurrentDataSend</code> by <code>TakeDynamicRequest</code>. This stage splits that upload into transfers; it does not count the full pose again for each request.

<code>DynamicRoutine</code> '''does not run DMA'''. It prepares requests for <code>VRAMDMA</code> to process during NMI.

=== What the sprite keeps ===

Sprite routines store the usable pose's hash index, not a separate copy of its graphics. The index lets them look up its VRAM block and update its last-use time.

If a new pose cannot be loaded:

* A valid previous pose is kept, and its last-use time is updated to protect it.
* If no valid pose has ever been available, the code must not draw as though the request succeeded.
* Calls supporting fallback to the previous pose may return carry set because a pose is still usable, even though the change has not completed.

Animation and movement remain the sprite's responsibility. The cache reuses or prepares the requested graphics.

=== Example: two sprites request the same pose ===

Suppose two visible sprites, A and B, need dynamic pose <code>$0005</code>. Their palettes are ready, the pose is not yet in VRAM, and enough space and data budget remain.

# '''Sprite A requests the pose.''' Lookup does not find <code>$0005</code> in the cache. The system chooses space, registers the pose, and prepares its graphics transfers. A stores the entry index in <code>!LastPoseHashIndex,x</code>. The graphics have not been copied to VRAM yet.
# '''A prepares its drawing.''' The drawing routine uses the registered entry to calculate tile numbers for that VRAM space and writes positions and properties to the OAM buffers.
# '''Sprite B requests the same pose.''' Lookup now finds <code>$0005</code> registered, even though its transfer is pending. It updates the last-use time without scheduling another upload. B stores the same cache index in its own <code>!LastPoseHashIndex,x</code>.
# '''B prepares its drawing.''' It writes its own tiles to the OAM buffers, using the same graphics as A with its own position, palette, and flip settings.
# '''NMI updates video data.''' The pending pose transfers copy the graphics to VRAM, and the game transfers the OAM buffers. Both sprites use the same uploaded graphics in the next displayed frame.

Only one pose upload is prepared, even though two sprites use it. That upload may require several DMA transfers, depending on the graphics layout in VRAM.

Here, a pose being '''available''' during logic means it has a registered entry, allocated space, and an upload prepared for NMI. If its graphics were already in VRAM, they are reused directly without preparing another transfer.

If A's request were rejected, the new pose would not be registered and no upload would be pending. A would use its previous pose if available; otherwise, it would have no pose to draw. B would need to handle its own request and would not find an entry created by A's rejected attempt.

== Palette effects: PalettesEffects ==

The system keeps the original colors so it can change effects, combine them, or restore the unaffected palette. An already affected result must not be treated as the original palette.

=== Color buffers ===

{| class="wikitable"
! Variable or buffer !! Total bytes !! Bytes per value !! Contents
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 per color || Base colors in SNES format, with 2 bytes per color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 per color || Base colors split into red, green, and blue, with 3 bytes per color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 per color || Base colors split into hue, saturation, and lightness, with 3 bytes per color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 per color || SNES-format result, ready for a CGRAM transfer request. Corresponds to the game's palette buffer.
|}

=== Per-palette flags ===

Each bit in these flags corresponds to one palette. <code>BG</code> variables cover 0–7; <code>SP</code> variables cover 8–F.

{| class="wikitable"
! Variables !! Total bytes !! Bytes per value !! Meaning
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> and <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the SNES-format color base has been prepared.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> and <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the base has been converted to RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> and <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the base has been converted to HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> and <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 per variable; 2 combined || 1; one bit per palette || Whether the global effect result is ready.
|}

These flags avoid repeating conversions and calculations whose results remain valid.

=== Preparing a base ===

# Checks whether the palette already has a registered base.
# If not, gets the colors from the game's buffer. An explicit upload, such as <code>TransferPalette</code>, can supply that base directly.
# Checks whether the effect needs RGB or HSL.
# If that conversion is missing, prepares it and marks it as available.

If only the effect changes, the base may remain valid. If the original colors change, upload calls update the base and invalidate conversions and results that must be recalculated.

=== Effect data ===

The ID selects data from the tables generated during installation:

* <code>Types</code>: calculation to perform.
* <code>Value1</code>, <code>Value2</code>, and <code>Value3</code>: channel values, or a transition's target palette address.
* <code>Ratio1</code>, <code>Ratio2</code>, and <code>Ratio3</code>: how much of each change to apply.

Channels range from 0 to 31. Ratios range from 0 to 127: 0 keeps the source unchanged, and 127 fully applies the selected change.

Calculations run outside NMI. NMI transfers the resulting colors.

=== Global effect ===

{| class="wikitable"
! Variable !! Total bytes !! Bytes per value !! Purpose
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selects the global effect. 0 restores the base colors.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; one bit per palette || Selects palettes 0–7 to receive the effect.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; one bit per palette || Selects palettes 8–F to receive the effect.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Last global effect ID processed for each palette.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controls whether the fixed color and color 0,0 are affected.
|}

For each enabled palette, the manager:

# Checks whether the effect result needs an update.
# Prepares the RGB or HSL base if missing.
# Calculates the effect if the previous result is no longer valid.
# Prepares SNES-format colors and requests their transfer.
# Records the processed ID when the corresponding upload is accepted.

If the effect and base remain unchanged, recalculation is unnecessary. Changing the global ID invalidates previous results, but not necessarily the RGB and HSL bases.

Global ID 0 also requires an update: the system must upload the base colors again to remove the previous effect.

=== Local effects and concatenation ===

A resource can have its own effect and also receive the global effect. For example, a sprite can change hue and then darken along with the level.

The order is:

# Prepare the local effect result.
# Use it as the global effect's base through the concatenation call.
# Calculate the global effect on that base.
# Upload the combined result without first displaying the local-only version.

* Use RGB concatenation for RGB effects.
* Use HSL concatenation for HSL effects.
* Resources sharing a CGRAM destination share its colors. To display two different local effects, they need destinations that can keep both results separately.

=== If the transfer is rejected ===

* Calculating an effect does not mean it is already in CGRAM.
* If the transfer is rejected, the manager can retry the update.
* Where supported, the previous usable result is kept until it can be replaced.
* Do not upload the unaffected original colors first: they could appear for one frame before the correct result.

== How the systems work together ==

A dynamic sprite brings these tasks together:

# Its logic selects the pose and palette version.
# Palette assignment finds a usable palette and prepares colors if needed.
# The cache protects the loaded pose or prepares a new upload.
# Drawing writes the pose's tiles to the OAM buffers.
# The effect manager prepares pending global changes.
# NMI performs the requested graphics and color transfers.

Sharing graphics, sharing a palette, and sharing a drawing routine are three different things. Dynamic Xtreme can take advantage of each without requiring resources to share the others.

Dynamic Xtreme ASM API

2026-10-25T21:57:36Z

Anonimzwx: Created page with "{{Select Language|Dynamic_Xtreme_ASM_API}} This article explains how to use Dynamic Xtreme's routines and macros from ASM code. Each entry explains the call's purpose, inputs, and results, with an example. To learn how to organize a complete sprite, see the sprite creation guide. == Features required to use the API == Available routines, macros, and variables depend on the features selected when installing Dynamic Xtreme. This..."

{{Select Language|Dynamic_Xtreme_ASM_API}}

This article explains how to use Dynamic Xtreme's routines and macros from ASM code. Each entry explains the call's purpose, inputs, and results, with an example.

To learn how to organize a complete sprite, see the [[Dynamic_Xtreme_sprite_creation_guide|sprite creation guide]].

== Features required to use the API ==

Available routines, macros, and variables depend on the features selected when installing Dynamic Xtreme. This table shows what to enable for each system:

{| class="wikitable"
! Feature !! Available routines and macros !! Dependencies and details
|-
| <code>GraphicsChange</code>
| [[#PPU|VRAM transfers]]: <code>TransferToVRAM</code> and its <code>FromAddr</code>, <code>Resource</code>, <code>WithLenght</code>, and <code>Forced</code> variants.
| Provides graphics loading. Also required by <code>DynamicPoses</code> and <code>PlayerFeatures</code>.
|-
| <code>DynamicPoses</code>
| [[#DefineDynamicSpaceConfig|DefineDynamicSpaceConfig]], [[#DynamicPoseSpaceConfig|DynamicPoseSpaceConfig]], [[#TakeDynamicRequest|TakeDynamicRequest]], [[#DynamicRoutine|DynamicRoutine]], <code>SetPropertyAndOffset</code>, [[#Upload|!Upload]], <code>!UploadWithoutPoseOffset</code>, and the general macros <code>GeneralUpload</code>, <code>Upload</code>, and <code>StandardSpriteUpload</code>.
| Requires <code>GraphicsChange</code>. Drawing the obtained poses also requires <code>DrawingSystem</code>.
|-
| <code>DrawingSystem</code>
| [[#DXDraw|!DXDraw]], <code>!DXDrawWithOffset</code>, and general macros <code>Draw</code>, <code>StandardSpriteDraw</code>, and [[#DrawStatic|DrawStatic]]. Includes the system's drawing and tile validation routines.
| Dynamic pose drawing also requires <code>DynamicPoses</code>. <code>DrawStatic</code> can draw static poses without the dynamic pose system.
|-
| <code>PalettesChange</code>
| <code>AssignPalette</code>, [[#PaletteAssignment|!PaletteAssignment]], <code>!PaletteAssignmentNoUpload</code>, <code>!ReplacePalette</code>, and their general macros; <code>LoadPaletteIDAndAddress</code>; [[#Uploading_colors_with_TransferPalette|TransferPalette]] macros and [[#PPU|CGRAM transfers]].
| Provides palette assignment and loading. Effects additionally require <code>PalettesEffects</code>.
|-
| <code>PalettesEffects</code>
| [[#Palette_effects|SetRGBBase, SetHSLBase, Mix, MixAndMerge, PaletteTransition, DoEffect, and RGB/HSL conversions]], including their variants. Also enables <code>ConcatenateRGBPaletteEffectToGlobal</code> and <code>ConcatenateHSLPaletteEffectToGlobal</code>, as sprite aliases or general macros.
| Requires <code>PalettesChange</code>. Allows global effects through palette assignment or <code>TransferPalette</code>.
|-
| <code>PlayerFeatures</code>
| Customizes player graphics and palettes through the [[#Player_and_Yoshi|player variables]]. Does not add a separate family of calls to the categories above.
| Requires <code>GraphicsChange</code> and <code>PalettesChange</code>.
|-
| <code>YoshiFeatures</code>
| Customizes Yoshi's graphics through the [[#Player_and_Yoshi|Yoshi variables]].
| Requires <code>PlayerFeatures</code> and its dependencies.
|-
| <code>Free7E2000</code>
| Adds no calls to this API.
| Frees and reorganizes the corresponding RAM area. Not an additional requirement for loading or drawing macros. Disabled on SA-1.
|-
| <code>ControllerOptimization</code>, <code>FixedColorOptimization</code>, <code>KevinLMVRAMOptimization</code>, and <code>StatusBarOptimization</code>
| Add no call families to this API.
| Change how their respective systems work internally. These are not required for pose, drawing, palette, or math macros.
|-
| No additional feature
| [[#Math|Mul, Div, and their W and After... variants]].
| Math macros are included from <code>DXDefines.asm</code> independently of the options above.
|}

PPU macros are included when <code>GraphicsChange</code> or <code>PalettesChange</code> is enabled, but use VRAM transfers with <code>GraphicsChange</code> and CGRAM transfers with <code>PalettesChange</code>. Asar recognizing a macro's name does not mean its required lists and variables are enabled.

To load '''and draw''' dynamic poses, enable <code>GraphicsChange</code>, <code>DynamicPoses</code>, and <code>DrawingSystem</code>. Add <code>PalettesChange</code> if the sprite loads palettes and <code>PalettesEffects</code> if it uses effects.

'''Tool integration'''

{| class="wikitable"
! Context !! Files and calls
|-
| PIXI
| Installation copies general defines to <code>asm/ExtraDefines</code> and shared routines to <code>routines</code>. For sprite aliases, include <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code>, or <code>ExtendedSpriteDefines.asm</code> as appropriate. Each entry explains type-specific differences.
|-
| UberASMTool
| Installation links <code>ExtraDefines/DXDefines.asm</code> from <code>other/macro_library.asm</code>. Use general macros and patch routines with their parameters; aliases such as <code>!Upload</code> belong to PIXI sprite defines files.
|-
| GPS
| Installation links <code>ExtraDefines/DXDefines.asm</code> from <code>defines.asm</code>. Use general macros and patch routines, preparing their inputs from the block's code.
|}

These integrations are prepared for tools configured during installation. If Asar cannot find a name, check the required feature, included files, and, for generated defines, the exact spelling in <code>DXDefines.asm</code>. After changing features or resources, reinstall Dynamic Xtreme and rerun tools using its defines, as explained in the [[Dynamic_Xtreme_Quick_Start|Quick Start guide]].

== Variables and defines ==

<code>DXDefines.asm</code> gathers the names Dynamic Xtreme uses for its variables, configurations, resources, and routines. Some represent runtime data; others are constants or generated during resource installation.

General variable names start with <code>DX_</code> and have no <code>!</code> prefix, for example <code>DX_Timer</code>. Defines such as <code>!DynamicPoseIDMySprite000</code> do include <code>!</code>. Keep each name's exact spelling.

Available variables depend on installed features. You do not need to memorize them all: find the category for the system you are using.

=== General variables ===

In these tables, size is the number of bytes occupied by one value. Tables also list their entry count. Dynamic Xtreme maintains variables marked internal; normally use API routines to work with them.

==== Counters and data per frame ====

{| class="wikitable"
! Variable !! Size !! Purpose
|-
| <code>DX_Timer</code> || 2 bytes || Counts frames in which Dynamic Xtreme runs. Continues during pause and frozen action. Used to track each pose's last use.
|-
| <code>DX_SyncTimer</code> || 2 bytes || Counts frames but stops during pause or frozen action. Useful for animations that should stop with the game.
|-
| <code>DX_Dynamic_CurrentDataSend</code> || 2 bytes || Bytes already scheduled for transfer in the current frame. Updated by loading routines.
|-
| <code>DX_Dynamic_MaxDataPerFrame</code> || 2 bytes || Maximum bytes normal uploads can schedule per frame. <code>Forced</code> variants can exceed it.
|}

==== Poses loaded in VRAM ====

These internal cache tables track which poses are loaded, where they are, and which remain in use. Request poses with <code>!Upload</code> or <code>!TakeDynamicRequest</code>.

{| class="wikitable"
! Variable !! Size !! Purpose
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 byte || Number of poses currently registered in the cache.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 one-byte values || Helps find poses by ID.
|-
| <code>DX_Dynamic_Pose_ID</code> || 128 two-byte values || ID of each registered pose.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 one-byte values || Location of each pose's graphics in dynamic VRAM space, measured in 16×16 blocks.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 128 two-byte values || <code>DX_Timer</code> at each pose's last use. Prevents replacement of graphics still being displayed.
|-
| <code>DX_Dynamic_Tile_Size</code> / <code>DX_Dynamic_Tile_Pose</code> || 128 shared bytes || Describe free and occupied VRAM regions. Two names for the same memory.
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 one-byte values || Helps traverse free and occupied VRAM regions.
|}

==== Palettes and the global effect ====

The 16-palette tables use palette order 0–F. In two-byte tables, palette 1 starts at <code>+2</code>, palette 2 at <code>+4</code>, and so on.

{| class="wikitable"
! Variable !! Size !! Purpose
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 byte || Each bit determines whether one of palettes 0–7 receives the global effect.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 byte || Each bit determines whether one of sprite palettes 8–F receives the global effect.
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 bytes || Desired global effect ID. Zero means no global effect.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectID</code> || 2 bytes || Last global effect examined by the system, used to detect changes.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 16 two-byte values || Last global effect calculated per palette. <code>$FFFF</code>: no result yet; <code>$FFFE</code>: update pending, previous result retained.
|-
| <code>DX_Dynamic_Palettes_ID</code> || 16 two-byte values || ID associated with each palette. <code>$FFFF</code> means free; <code>$FFFE</code> excludes it from automatic selection.
|-
| <code>DX_Dynamic_Palettes_Updated</code> || 16 one-byte values || Palettes already updated this frame. Internal.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 one-byte values || A nonzero timer protects a palette from replacement by another automatic assignment. Calls using it reset it to 2.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 byte || Tracks sprite palettes using effects. Internal palette management state.
|}

To reserve a sprite palette against automatic selection, set its <code>DX_Dynamic_Palettes_ID</code> entry to <code>$FFFE</code> before sprites request palettes.

==== Color copies and effect results ====

{| class="wikitable"
! Variable !! Size !! Purpose
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 bytes || Working copy of 256 colors at 2 bytes each. Source for <code>SetRGBBaseDefault</code> and <code>SetHSLBaseDefault</code>.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 bytes || Original colors split into red, green, and blue: 3 bytes per color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 bytes || Original colors split into hue, saturation, and lightness: 3 bytes per color.
|-
| <code>DX_PPU_CGRAM_LocalEffectBuffer</code> || 768 bytes || Working space for a local effect result before combining it with the global effect.
|-
| <code>DX_PPU_CGRAM_LocalEffectID</code> || 16 two-byte values || Local effect ID applied to each palette.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 bytes || Resulting colors in SNES format, 2 bytes each. <code>AndMergeDefault</code> variants write here.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> / <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 byte each || Each bit indicates a background or sprite palette's RGB base is prepared.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> / <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 byte each || Same for HSL bases.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> / <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 byte each || Each bit indicates an available effect result for that palette.
|-
| <code>DX_PPU_CGRAM_LastPlayerPal</code> || 2 bytes || Last processed player palette address, compared to detect changes.
|}

Writing colors to a RAM copy does not immediately send them to CGRAM. Use palette routines or a transfer to update the display. The system manages prepared-base and effect flags; they do not need clearing before each call.

==== Fixed color and the first palette color ====

The SNES fixed color can be used for color addition and subtraction effects. Color 0,0 is CGRAM's first entry. Dynamic Xtreme can apply the global effect to either independently.

{| class="wikitable"
! Variable !! Size !! Purpose
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 byte || Enables the global effect: bit <code>$01</code> for fixed color and <code>$02</code> for color 0,0. <code>$03</code> enables both.
|-
| <code>DX_PPU_ColorEffect_BaseLoaded</code> || 1 byte || Tracks saved original colors, one bit per target: <code>$01</code> and <code>$02</code>.
|-
| <code>DX_PPU_ColorEffect_RGBBaseLoaded</code> / <code>DX_PPU_ColorEffect_HSLBaseLoaded</code> || 1 byte each || Tracks prepared RGB/HSL colors, using the same bits.
|-
| <code>DX_PPU_FixedColor_Mirror</code> || 2 bytes || Fixed color copy used by the game's normal update.
|-
| <code>DX_PPU_FixedColor_Base</code> || 2 bytes || Original fixed color before effects.
|-
| <code>DX_PPU_FixedColor_RGBBase</code> / <code>DX_PPU_FixedColor_HSLBase</code> || 3 bytes each || Original fixed color split into RGB or HSL.
|-
| <code>DX_PPU_FixedColor_Result</code> || 2 bytes || Fixed color calculated after the effect.
|-
| <code>DX_PPU_FixedColor_LastGlobalEffectID</code> || 2 bytes || Last global effect calculated for fixed color.
|-
| <code>DX_PPU_PaletteColor00_Base</code> || 2 bytes || Original color 0,0.
|-
| <code>DX_PPU_PaletteColor00_RGBBase</code> / <code>DX_PPU_PaletteColor00_HSLBase</code> || 3 bytes each || Original color 0,0 split into RGB or HSL.
|-
| <code>DX_PPU_PaletteColor00_Result</code> || 2 bytes || Desired color 0,0.
|-
| <code>DX_PPU_PaletteColor00_LastGlobalEffectID</code> || 2 bytes || Last global effect calculated for color 0,0.
|-
| <code>DX_PPU_PaletteColor00_Update</code> || 1 byte || Nonzero requests copying <code>Result</code> to color 0,0 during NMI. Reset to 0 afterward.
|}

==== Pending transfers ====

These variables store copies to perform during NMI. PPU macros populate them for you. Each copy needs a source, destination, and byte count.

{| class="wikitable"
! Variable !! Contents
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || Pending graphics copy count, 1 byte.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || Bytes per copy, two-byte values.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || Each copy's VRAM destination, two-byte values.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || Each copy's source address, two-byte values.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || Each copy's source bank. The table reserves 2 bytes per entry.
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || Pending color copy count, 1 byte.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || Bytes per copy, two-byte values.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || Each copy's first destination color, one-byte values.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || Each copy's source address, two-byte values.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || Each copy's source bank.
|}

==== Player and Yoshi ====

These variables change the sources of player graphics and colors and Yoshi graphics. Graphics files must retain the layout expected by the game routines.

{| class="wikitable"
! Variable !! Size !! Purpose
|-
| <code>DX_Dynamic_Player_GFX_Enable</code> || 1 byte || Zero disables player graphics loading through this system; nonzero enables it.
|-
| <code>DX_Dynamic_Player_GFX_Addr</code> || 2 bytes || Player graphics start address within the specified bank.
|-
| <code>DX_Dynamic_Player_GFX_BNK</code> || 2 bytes reserved || Player graphics source bank, specified in the low byte.
|-
| <code>DX_Dynamic_Player_Palette_Enable</code> || 1 byte || Zero disables player palette management through this system; nonzero enables it.
|-
| <code>DX_Dynamic_Player_Palette_Addr</code> || 2 bytes || Player palette source address.
|-
| <code>DX_Dynamic_Player_Palette_BNK</code> || 1 byte || Palette bank. When zero, the routine uses the game's player palette address.
|-
| <code>DX_Dynamic_Player_CustomPlayer</code> / <code>DX_Dynamic_Player_LastCustomPlayer</code> || 1 byte each || Reserved to identify current and previous custom players. Initialized to 0 and <code>$FF</code>; currently do not select character graphics by themselves.
|-
| <code>DX_Dynamic_Yoshi_VRAMEnable</code> || 1 byte || Zero disables Yoshi graphics loading through this system; nonzero enables it.
|-
| <code>DX_Dynamic_Yoshi_Addr</code> || 2 bytes || Yoshi graphics start address within the bank.
|-
| <code>DX_Dynamic_Yoshi_BNK</code> || 1 byte || Yoshi graphics source bank.
|}

==== Drawing and sprite variables ====

<code>DX_Drawing_InitialIndexHighPriority</code> and <code>DX_Drawing_InitialIndexLowPriority</code> each occupy 1 byte and track available drawing positions for high- and low-priority sprites. <code>DX_Drawing_OAMMap</code> occupies 128 bytes and helps organize drawn tiles. These variables are used on LoROM; SA-1 uses its corresponding drawing management.

Individual sprite variables are defined in <code>DynamicXSpritesTables.asm</code>. <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code>, and <code>ExtendedSpriteDefines.asm</code> let all three types use the same names:

{| class="wikitable"
! Sprite name !! Contents
|-
| <code>!PoseIndex,x</code> || Desired pose.
|-
| <code>!LastPoseIndex,x</code> || Last obtained pose available for drawing. Initialize to <code>$FF</code>.
|-
| <code>!LastPoseHashIndex,x</code> || Cache entry tracking the graphics' location. Initialize to <code>$FF</code>.
|-
| <code>!GlobalFlip,x</code> / <code>!LocalFlip,x</code> / <code>!LastFlip,x</code> || Overall flip, additional pose flip, and effective drawing flip.
|-
| <code>!Palette,x</code> || Assigned palette: <code>$00</code> for 8, <code>$02</code> for 9, through <code>$0E</code> for F. Initialize to <code>$FF</code> for dynamic assignment.
|-
| <code>!PaletteOption,x</code> || <code>EPPP----</code> options: global effect and palette or palette-group selection.
|-
| <code>!PaletteAssignmentOption,x</code> || Assignment mode: automatic, manual, or manual without uploading colors.
|-
| <code>!Version,x</code> / <code>!LastVersion,x</code> || Sprite variant and last variant processed for its palette. Initialize <code>!LastVersion</code> to <code>$FF</code>.
|-
| <code>!RenderXDistanceOutOfScreen,x</code> / <code>!RenderYDistanceOutOfScreen,x</code> || Distances that allow drawing when the sprite's position is offscreen but some of its pose may remain visible.
|-
| <code>!SafeFrameLowByte,x</code> / <code>!SafeFrameHighByte,x</code> || Last frame a pose request was attempted, preventing repeated work in the same frame.
|-
| <code>!AnimationIndex,x</code> / <code>!AnimationPoseIndex,x</code> / <code>!AnimationTimer,x</code> || Available variables for the animation, current step, and timer. The resource's code decides how to use them.
|-
| <code>!State,x</code> || Resource state or behavior variable.
|}

Each variable occupies 1 byte per sprite. Normal sprites have <code>!MaxSprites</code> entries, cluster sprites 20, and extended sprites 10. Do not use <code>!MaxSprites</code> as the cluster or extended entry count.

<code>DX_FreeRams</code> and <code>DX_FreeRams2</code> mark the start of these table areas. They are not free memory for storing your own data over sprite variables.

=== Fixed defines ===

These names represent known configurations and addresses, not variables that change during gameplay.

==== LoROM and SA-1 compatibility ====

<code>DXDefines.asm</code> detects the ROM type and selects the corresponding values. Use these names to support both types.

{| class="wikitable"
! Define !! LoROM !! SA-1 !! Use
|-
| <code>!sa1</code> || 0 || 1 || Select different code by ROM type.
|-
| <code>!dp</code> || <code>$0000</code> || <code>$3000</code> || Direct-page address adjustment.
|-
| <code>!addr</code> || <code>$0000</code> || <code>$6000</code> || RAM address adjustment where required, for example <code>$0100|!addr</code>.
|-
| <code>!rom</code> || <code>$800000</code> || <code>$000000</code> || Adjustment for original game code addresses.
|-
| <code>!MaxSprites</code> || <code>$0C</code> (12) || <code>$16</code> (22) || Normal sprite slot count.
|-
| <code>!MultiplicationResult</code> || <code>$4216</code> || <code>$2306</code> || Multiplication result address.
|-
| <code>!DivisionResult</code> || <code>$4214</code> || <code>$2306</code> || Division quotient address.
|-
| <code>!RemainderResult</code> || <code>$4216</code> || <code>$2308</code> || Division remainder address.
|}

Other variable-placement defines are <code>!normalBnk</code>, <code>!PalCopyBNK</code>, <code>!Variables</code>, and <code>!Variables2</code>. Normally, use each <code>DX_...</code> variable's name rather than calculate its address from these values.

==== Graphics addresses in VRAM ====

These defines specify transfer destinations without numeric addresses. Each family has lines 0 through 7; replace N with the line number.

{| class="wikitable"
! Family !! Line 0 !! Increment per line !! Example
|-
| <code>!FG1LineN</code> || <code>$0000</code> || <code>$0100</code> || <code>!FG1Line1 = $0100</code>
|-
| <code>!FG2LineN</code> || <code>$0800</code> || <code>$0100</code> || <code>!FG2Line1 = $0900</code>
|-
| <code>!BG1LineN</code> || <code>$1000</code> || <code>$0100</code> || <code>!BG1Line1 = $1100</code>
|-
| <code>!FG3LineN</code> || <code>$1800</code> || <code>$0100</code> || <code>!FG3Line1 = $1900</code>
|-
| <code>!BG2LineN</code> || <code>$2000</code> || <code>$0100</code> || <code>!BG2Line1 = $2100</code>
|-
| <code>!BG3LineN</code> || <code>$2800</code> || <code>$0100</code> || <code>!BG3Line1 = $2900</code>
|-
| <code>!LG1LineN</code> through <code>!LG4LineN</code> || <code>$4000</code>, <code>$4400</code>, <code>$4800</code>, <code>$4C00</code> || <code>$0080</code> || <code>!LG1Line1 = $4080</code>
|-
| <code>!SP1LineN</code> through <code>!SP4LineN</code> || <code>$6000</code>, <code>$6800</code>, <code>$7000</code>, <code>$7800</code> || <code>$0100</code> || <code>!SP4Line1 = $7900</code>
|}

<code>!Layer1Tilemap = $3000</code> and <code>!Layer2Tilemap = $3800</code> are the usual Layer 1 and Layer 2 tilemap addresses. VRAM addresses here use 2-byte words, as do the transfer macros.

==== Space configurations for dynamic poses ====

Pass <code>!DynamicSpaceConfig...</code> defines to <code>!DynamicPoseSpaceConfig</code>. Each name identifies the allowed graphics areas. <code>FirstHalf</code> and <code>SecondHalf</code> identify half-areas. Names containing <code>WithPlayer</code> or <code>WithDSX</code> are intended for those configurations.

{| class="wikitable"
! Value !! Define
|-
| <code>$00</code> || <code>!DynamicSpaceConfigSecondHalfSSP4</code>
|-
| <code>$01</code> || <code>!DynamicSpaceConfigSP4</code>
|-
| <code>$02</code> || <code>!DynamicSpaceConfigSecondHalfSP3</code>
|-
| <code>$03</code> || <code>!DynamicSpaceConfigFirstHalfSP3</code>
|-
| <code>$04</code> || <code>!DynamicSpaceConfigSP3</code>
|-
| <code>$05</code> || <code>!DynamicSpaceConfigSecondHalfSP2</code>
|-
| <code>$06</code> || <code>!DynamicSpaceConfigFirstHalfSP2</code>
|-
| <code>$07</code> || <code>!DynamicSpaceConfigSP2</code>
|-
| <code>$08</code> || <code>!DynamicSpaceConfigSecondHalfSP1</code>
|-
| <code>$09</code> || <code>!DynamicSpaceConfigFirstHalfSP1</code>
|-
| <code>$0A</code> || <code>!DynamicSpaceConfigSP1</code>
|-
| <code>$0B</code> || <code>!DynamicSpaceConfigFirstHalfSP1WithPlayer</code>
|-
| <code>$0C</code> || <code>!DynamicSpaceConfigSP11WithPlayer</code>
|-
| <code>$0D</code> || <code>!DynamicSpaceConfigSecondHalfSP3ndSP4</code>
|-
| <code>$0E</code> || <code>!DynamicSpaceConfigSP34</code>
|-
| <code>$0F</code> || <code>!DynamicSpaceConfigSecondHalfSP2andSP34</code>
|-
| <code>$10</code> || <code>!DynamicSpaceConfigSP234</code>
|-
| <code>$11</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234</code>
|-
| <code>$12</code> || <code>!DynamicSpaceConfigSP1234</code>
|-
| <code>$13</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithPlayer</code>
|-
| <code>$14</code> || <code>!DynamicSpaceConfigSP1234WithPlayer</code>
|-
| <code>$15</code> || <code>!DynamicSpaceConfigSecondHalfSP3ndSP4WithDSX</code>
|-
| <code>$16</code> || <code>!DynamicSpaceConfigSP34WithDSX</code>
|-
| <code>$17</code> || <code>!DynamicSpaceConfigSecondHalfSP2andSP34WithDSX</code>
|-
| <code>$18</code> || <code>!DynamicSpaceConfigSP234WithDSX</code>
|-
| <code>$19</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithDSX</code>
|-
| <code>$1A</code> || <code>!DynamicSpaceConfigSP1234WithDSX</code>
|-
| <code>$1B</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithPlayerAndDSX</code>
|-
| <code>$1C</code> || <code>!DynamicSpaceConfigSP1234WithPlayerAndDSX</code>
|}

Spell these names exactly as published in <code>DXDefines.asm</code>, including names such as <code>SecondHalfSSP4</code> and <code>SP11WithPlayer</code>.

==== Other constants ====

{| class="wikitable"
! Define !! Value or use
|-
| <code>!AN2Buffer1</code> / <code>!AN2Buffer2</code> || Animation data addresses <code>$7EC100</code> and <code>$7EAD00</code>.
|-
| <code>!GFX32Buffer</code> || <code>$7E2000</code>, the usual GFX32 buffer address.
|-
| <code>!PlayerPaletteColor2To5</code> || <code>$00B280</code>, player palette colors 2–5.
|-
| <code>!PlayerBasePalette</code> || <code>$00B2C8</code>, player base palette data.
|-
| <code>!VRAMTransferSize</code> / <code>!CGRAMTransferSize</code> || Both are 64 in the current template. Reserve transfer tables; they are not the per-frame byte limit.
|}

Installation options such as <code>!DynamicPoses</code>, <code>!DrawingSystem</code>, <code>!GraphicsChange</code>, <code>!PalettesChange</code>, <code>!PalettesEffects</code>, <code>!PlayerFeatures</code>, and <code>!YoshiFeatures</code> come from <code>Options.asm</code>. They identify installed features and are not changed at runtime.

=== Generated defines ===

Dynamic Xtreme creates these defines during resource installation and adds them to <code>DXDefines.asm</code>. Use their names rather than copied numeric values, because IDs, addresses, and sizes may change when resources are added or modified.

Names use PascalCase normalization: remove spaces, underscores, hyphens, and other separators and capitalize each word's first letter. For example, <code>my_sprite</code>, <code>my-sprite</code>, and <code>my sprite</code> become <code>MySprite</code>. Other existing capitalization is preserved. When unsure, copy the exact name from <code>DXDefines.asm</code>.

==== Dynamic poses and drawing poses ====

{| class="wikitable"
! Family or example !! Meaning
|-
| <code>!DynamicPoseIDMySprite000</code> || ID of pose graphics declared in DynamicInfo. Used to request loading with <code>!Upload</code>.
|-
| <code>!DynamicPoseMySprite000</code> || ROM address of those graphics.
|-
| <code>!DynamicPoseMySprite000Size</code> || Graphics data size in bytes.
|-
| <code>!PoseIDMySprite_Frame0</code> || DrawInfo pose ID. Used for drawing with <code>!DXDraw</code> or <code>DrawStatic</code>.
|-
| <code>!RenderBoxXDistanceOutOfScreenMySprite</code> || Horizontal distance calculated from DrawInfo to determine when the sprite is no longer visible.
|-
| <code>!RenderBoxYDistanceOutOfScreenMySprite</code> || Vertical distance for the same check.
|}

Dynamic IDs choose which graphics to load; drawing IDs choose how tiles form the pose. These are different values. Do not substitute a <code>!DynamicPoseID...</code> for a <code>!PoseID...</code>.

==== Palettes and effects ====

{| class="wikitable"
! Family or example !! Meaning
|-
| <code>!PaletteIDMyPalette</code> || ID of a palette declared in DynamicInfo.
|-
| <code>!PaletteMyPalette</code> || ROM address of its colors.
|-
| <code>!PaletteMyPaletteSize</code> || Palette size in bytes.
|-
| <code>!MySpritePaletteTableOffset</code> || Start of that DynamicInfo's palette list. Passed to <code>!PaletteAssignment</code> and its variants.
|-
| <code>!PaletteEffectIDMyEffect0</code> || Effect ID from <code>my_effect.paleffect</code>. The suffix is the effect's index within the file; global IDs start at 1.
|-
| <code>!PaletteMyTargetRGB</code> / <code>!PaletteMyTargetHSL</code> || ROM address of a target palette converted for an RGB/HSL transition. Generated when an effect needs that palette.
|-
| <code>!PaletteMyTargetRGBSize</code> / <code>!PaletteMyTargetHSLSize</code> || Converted palette sizes in bytes.
|}

Example names follow the same normalization: <code>my_palette</code> becomes <code>MyPalette</code> and <code>my_effect</code> becomes <code>MyEffect</code>. Defines are generated during installation and stored in <code>DXDefines.asm</code>.

==== General resources and buffers ====

{| class="wikitable"
! Family or example !! Meaning
|-
| <code>!ResourceIDMyResource</code> || General resource ID from DynamicInfo.
|-
| <code>!ResourceMyResource</code> || Resource ROM address.
|-
| <code>!ResourceMyResourceSize</code> || Resource size in bytes.
|-
| <code>!BufferIDMyBuffer</code> || ID of a tool-inserted buffer.
|-
| <code>!BufferMyBuffer</code> || ROM address of the inserted buffer, not temporary RAM.
|-
| <code>!BufferMyBufferSize</code> || Buffer size in bytes.
|}

Names depend on installed resources and use the same normalization: <code>my_resource</code> becomes <code>MyResource</code>. Check <code>DXDefines.asm</code> for your installation's names and values.

==== Generated counts and tables ====

These defines expose counts and tables generated during installation. Normal sprites usually need only the individual IDs in the tables above.

{| class="wikitable"
! Define !! Meaning
|-
| <code>!NumberOfDynamicPoses</code> / <code>!NumberOfPoses</code> || Installed dynamic pose count and drawing pose count, respectively.
|-
| <code>!NumberOfPalettes</code> / <code>!NumberOfResources</code> / <code>!NumberOfBuffers</code> || Inserted normal palette, general resource, and buffer counts.
|-
| <code>!NumberOfPaletteEffects</code> || Value used to size effect tables. Generation includes space for ID 0; do not interpret this as a single <code>*.paleffect</code> file's effect count.
|-
| <code>!PaletteTableSize</code> || Total entries in DynamicInfo palette lists.
|-
| <code>!PaletteIDTables</code> || Address of those lists' ID table.
|-
| <code>!PaletteAddrTables</code> || Address of the table containing their color ROM addresses.
|-
| <code>!PaletteEffectsTypes</code> || Table of installed effect types.
|-
| <code>!PaletteEffectsChannels1</code>, <code>!PaletteEffectsChannels2</code>, <code>!PaletteEffectsChannels3</code> || Tables of each effect's color values.
|-
| <code>!PaletteEffectsRatios1</code>, <code>!PaletteEffectsRatios2</code>, <code>!PaletteEffectsRatios3</code> || Ratio tables controlling each change's strength.
|-
| <code>!BufferTable</code>, <code>!PaletteTables</code>, <code>!PaletteEffectsTable</code> || Table addresses published by the patch.
|}

=== Routine defines ===

These defines represent system calls, not data variables. This table helps locate them; their use is explained in the routine and macro sections.

{| class="wikitable"
! Define or family !! Use
|-
| <code>!AllowedGameMode</code> || Checks whether the current game mode permits the corresponding operations.
|-
| <code>!DynamicPoseSpaceConfig</code> || Selects VRAM regions available for dynamic poses.
|-
| <code>!TakeDynamicRequest</code> || Requests a pose by ID.
|-
| <code>!DynamicRoutine</code> || Prepares pose graphics transfers to VRAM.
|-
| <code>!SetPropertyAndOffset</code> || Gets a dynamic pose's graphics location and properties for drawing.
|-
| <code>!Draw</code> / <code>!Draw_Return</code> || Drawing routine entry and return point.
|-
| <code>!RemapOamTile</code> || Adjusts tile numbers for the actual dynamic graphics location.
|-
| <code>!IsValid</code>, <code>!XIsValid</code>, <code>!YIsValid</code> || Drawing checks to determine tile visibility.
|-
| <code>!AssignPalette</code> || Selects a palette destination according to assignment mode.
|-
| <code>!LoadPaletteOnBuffer</code> || Loads palette data into a working buffer.
|-
| <code>!SetRGBBase</code> / <code>!SetHSLBase</code> || Prepares colors for RGB/HSL effects.
|-
| <code>!RGBToHSL</code> / <code>!HSLToRGB</code> || Converts between color spaces.
|-
| <code>!RGBMerge</code> || Converts separate RGB colors to SNES palette format.
|-
| <code>!Mix...</code> / <code>!MixAndMerge...</code> || Changes one or more color components.
|-
| <code>!PalTransitionRGB</code> / <code>!PalTransitionHSL</code> || Calculates a palette transition.
|-
| <code>!PalTransitionAndMergeRGB</code> / <code>!PalTransitionAndMergeHSL</code> || Calculates a transition and produces SNES-format colors.
|-
| <code>!DoEffect</code> / <code>!DoEffectAndMerge</code> || Applies an effect by ID.
|-
| <code>!PalFunctionRGB</code>, <code>!PalFunctionHSL</code>, and <code>AndMerge</code> variants || Reserved names for color functions not implemented yet.
|}

<code>!Routines</code> is the table address used to obtain these calls. You do not need to calculate offsets to use published defines.

== CPU state and temporary memory ==

Each call requires the register widths specified in its inputs. A register can return in 8-bit mode while losing its previous value: '''width and contents are different things'''.

Unless an entry states otherwise, these rules apply throughout this article:

* Run in native mode with decimal mode disabled. The system's arithmetic uses binary numbers.
* '''Direct page D:''' <code>$0000</code> on LoROM and <code>$3000</code> in the usual SA-1 Pack context. Short addresses such as <code>$00</code> are relative to that base. Calls do not prepare or change D for you.
* '''Data bank DBR:''' must allow access to the RAM mirrors and hardware registers used by the call. The usual context uses banks with these mirrors, such as <code>$00-$3F</code> or <code>$80-$BF</code>. If an operand reads a table through a 16-bit address, DBR must also allow access to that table. A 24-bit pointer carries its own bank. <code>DynamicRoutine</code> has a specific DBR requirement explained in its entry.
* Calls preserve DBR and D. Some change DBR temporarily and restore it before returning. This does not make every input bank valid.
* '''Flags:''' only use explicitly documented output flags. Do not assume N, Z, V, or carry retain their old values. A and X/Y width changes are specified per call.
* '''Temporary memory:''' listed scratch may be overwritten on success or failure. Save values needed afterward elsewhere. Outputs are valid only under the stated conditions.
* '''Stack:''' calls remove their own temporary stack data. Match your own pushes and pulls at the same register width and respect the routine or macro's return type.

To preserve a register, save it before the call and restore it afterward at the same width. Check returned carry before another operation changes it; restoring P with <code>PLP</code> also replaces that carry.

== Sprite routines ==

These routines check whether a sprite should be drawn, load its graphics, and manage its palettes. Include the appropriate defines file first: <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code>, or <code>ExtendedSpriteDefines.asm</code>. Its path is relative to the sprite ASM.

DBR, D, flag, and stack requirements are explained in [[#CPU_state_and_temporary_memory|CPU state and temporary memory]]. The table below distinguishes register widths from preserved values.

Write calls such as <code>!RenderBox</code> or <code>!Upload</code> directly, as in the examples. Do not prefix them with <code>JSR</code> or <code>JSL</code>. Unless stated otherwise, X must contain the sprite slot index.

'''Sprite call registers and scratch'''

Enter with 8-bit X and Y. A's width depends on the call:

{| class="wikitable"
! Call !! A on entry !! Registers on return !! Scratch potentially overwritten
|-
| <code>!RenderBox</code>
| 8 bits.
| A changes and returns in 8-bit mode. X and Y retain their values and widths.
| No scratch; modifies the Dynamic Xtreme tables described in its entry.
|-
| <code>!PaletteAssignment</code> and <code>!PaletteAssignmentNoUpload</code>
| 16 bits with <code>PalettesChange</code> enabled; 8 bits when disabled, without using the table offset.
| A and Y may change. X is reloaded from <code>!SpriteIndex</code> when used internally. The no-upload variant returns information in Y. All three return in 8-bit mode.
| <code>$00-$0F</code>, <code>$65-$67</code>, and <code>$D5</code>, depending on the path. With effects, may also use the effect temporaries listed below.
|-
| <code>!Upload</code> and <code>!UploadWithoutPoseOffset</code>
| 16 bits.
| A and Y may change. X is restored from <code>!SpriteIndex</code>. All three return in 8-bit mode.
| <code>$00-$0F</code> and <code>$47-$51</code> when preparing a new load.
|-
| <code>!DXDraw</code> and <code>!DXDrawWithOffset</code>
| 16 bits.
| A and Y may change. When drawing, X is restored from <code>!SpriteIndex</code>; if no valid pose exists, input X is retained. All three return in 8-bit mode.
| <code>$00-$0F</code>, <code>$45-$4F</code>, and <code>$8A</code>. Additional offsets also use <code>$8B-$8C</code>.
|-
| <code>!ReplacePalette</code>
| 8 bits.
| A and Y may change. X is restored from <code>!SpriteIndex</code>. All three return in 8-bit mode.
| <code>$00-$01</code> and temporaries used for color loading; effect temporaries when applicable.
|-
| <code>!ConcatenateRGBPaletteEffectToGlobal</code> and its HSL variant
| 16 bits.
| A and Y may change. X takes a palette on entry but contains <code>!SpriteIndex</code> on return. All three return in 8-bit mode.
| Effect temporaries, <code>$05-$06</code>, and <code>$F0-$F3</code>.
|}

PIXI maintains <code>!SpriteIndex</code> as the current sprite index. If you temporarily change X, calls restoring that index do not necessarily preserve the X value you supplied. After effect concatenation, X identifies the sprite again, not its palette. PIXI aliases call their shared routines and continue at the next instruction; the examples' <code>RTS</code> belongs to the sprite's own routine.

=== RenderBox ===

<code>!RenderBox</code> checks whether the sprite is on screen or close enough to its edges to keep drawing. Use it at the start of the main routine to choose between core logic only (short routine) or graphics loading, palette management, and drawing as well (long routine).

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalRenderBox()</code>.
* Cluster sprite: <code>%DXClusterRenderBox()</code>.
* Extended sprite: <code>%DXExtendedRenderBox()</code>.

'''Inputs'''

* X: sprite index.
* <code>!RenderXDistanceOutOfScreen,x</code> and <code>!RenderYDistanceOutOfScreen,x</code>: allowed horizontal and vertical distances outside the screen.

'''Result'''

* Carry set: the sprite is on screen or within the allowed offscreen distance; run the long routine.
* Carry clear: the sprite is too far offscreen to draw; run the short routine.

When too far offscreen, sets <code>!Palette</code>, <code>!LastVersion</code>, <code>!LastPoseIndex</code>, and <code>!LastPoseHashIndex</code> to <code>$FF</code>, indicating that palette and pose must be obtained again when it returns. Also combines <code>!GlobalFlip</code> and <code>!LocalFlip</code> into <code>!LastFlip</code>. For normal sprites, updates horizontal and vertical offscreen flags as well.

'''Example'''

<pre>
print "INIT ",pc
LDA.b #!RenderBoxXDistanceOutOfScreenMySprite
STA !RenderXDistanceOutOfScreen,x
LDA.b #!RenderBoxYDistanceOutOfScreenMySprite
STA !RenderYDistanceOutOfScreen,x
; Put the rest of the sprite initialization here
RTL

SpriteCode:
!RenderBox
BCS .LongRoutine

.ShortRoutine
LDA #$00
%SubOffScreen()
; Put your sprite's logic here
RTS

.LongRoutine
; Put palette management, pose loading, drawing,
; and your sprite's logic here
RTS
</pre>

The example's <code>%SubOffScreen()</code> is for normal sprites and takes A from 0 to 7 to select offscreen removal settings. It uses the usual value, 0. Calling it in the short routine is recommended; it is redundant in the long routine.

<code>!RenderBoxXDistanceOutOfScreenMySprite</code> and <code>!RenderBoxYDistanceOutOfScreenMySprite</code> are generated from DrawInfo and stored in <code>DXDefines.asm</code>. Resource names use PascalCase: remove spaces, underscores, and hyphens and capitalize each word's first letter. For example, <code>my_sprite</code> becomes <code>MySprite</code>. With multiple DrawInfo files, use the largest horizontal and vertical distances among them.

=== PaletteAssignment ===

<code>!PaletteAssignment</code> selects a DynamicInfo palette using <code>!Version,x</code>, assigns it to one of sprite palettes 8–F, and loads its colors when needed. If already assigned, resets its protection timer to 2 so another resource cannot replace it. Call every long-routine frame; this does not mean colors are uploaded every time.

If bit <code>E</code> of <code>!PaletteOption,x</code> is set (<code>$80</code>), it also processes the corresponding global palette effects. Otherwise the palette is excluded from the global effect.

'''How the palette is selected'''

<code>!Version,x</code> selects an entry from DynamicInfo's palette list: 0 for the first, 1 for the second, and so on. For a list containing red and blue palettes, versions 0 and 1 select those colors. Sprite behavior may also depend on this variable; palette management only uses it to select colors.

<code>!PaletteOption,x</code> determines which sprite palette may be used and whether it receives the global effect. Format: <code>EPPP----</code>:

* <code>E</code>: 0 excludes the palette from the global effect; 1 allows it.
* <code>PPP</code>: in manual mode, selects palette 8–F. <code>000</code> selects 8, <code>001</code> selects 9, through <code>111</code> for F.
* In automatic mode, <code>PPP = 000</code> allows all eight palettes. Nonzero <code>0XX</code> limits the search to 8–B; <code>1XX</code> limits it to C–F.
* The low four bits are unused by these options.

<code>!PaletteAssignmentOption,x</code> determines who chooses the destination and whether colors are uploaded. Format: <code>--AA----</code>:

* <code>AA = 00</code> (<code>$00</code>): automatic. Dynamic Xtreme chooses an allowed palette and loads DynamicInfo's colors.
* <code>AA = 01</code> (<code>$10</code>): manual. Uses the palette specified by <code>PPP</code> and loads DynamicInfo's colors.
* <code>AA = 10</code> (<code>$20</code>): manual without upload. Uses the specified palette with the level's existing colors.

For normal sprites, <code>!PaletteOption,x</code> is <code>!ExtraByte1,x</code> and <code>!PaletteAssignmentOption,x</code> is <code>!ExtraProp2,x</code>. Commonly use <code>EPPPVVVV</code> in Extra Byte 1 and copy its low four bits to <code>!Version,x</code> in INIT, selecting the version through Lunar Magic. For cluster and extended sprites, the spawning code must set these variables.

For example, manual <code>!PaletteOption,x = $A0</code> uses palette A and allows the global effect. With <code>!Version,x = 1</code>, it loads the second palette from DynamicInfo.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalPaletteAssignment()</code>.
* Cluster sprite: <code>%DXClusterPaletteAssignment()</code>.
* Extended sprite: <code>%DXExtendedPaletteAssignment()</code>.

'''Inputs'''

* 16-bit A: <code>!MySpritePaletteTableOffset</code> for the DynamicInfo containing the palettes.
* X: sprite index.
* <code>!Version,x</code>: palette index in the table.
* <code>!LastVersion,x</code>: last processed version, compared with <code>!Version,x</code> to detect changes. Initialize to <code>$FF</code>.
* <code>!PaletteOption,x</code>: palette selection and participation in the global effect.
* <code>!PaletteAssignmentOption,x</code>: automatic, manual, or manual-without-upload assignment.

'''Result'''

* Carry set: the sprite can be drawn with the assigned palette.
* Carry clear: the sprite has no palette ready for drawing yet.
* <code>!Palette,x</code>: assigned palette, increasing by two from <code>$00</code> to <code>$0E</code> for palettes 8–F.
* <code>!LastVersion,x</code>: updated to <code>!Version,x</code> when the new assignment is processed.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignment
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> is generated from DynamicInfo and stored in <code>DXDefines.asm</code>. The resource name uses PascalCase normalization: remove separators and capitalize each word's first letter, so <code>my_sprite</code> becomes <code>MySprite</code>.

=== PaletteAssignmentNoUpload ===

<code>!PaletteAssignmentNoUpload</code> selects a palette like <code>!PaletteAssignment</code> but leaves the color upload pending. Use it to modify the palette first, for example by applying a local effect combined with the global effect. If already assigned, resets its protection timer to 2 against replacement.

Bit <code>E</code> of <code>!PaletteOption,x</code> (<code>$80</code>) also controls global effects. This variant prepares assignment and the base palette; a subsequent routine such as <code>!ConcatenateRGBPaletteEffectToGlobal</code> or <code>!ConcatenateHSLPaletteEffectToGlobal</code> completes the effects and upload.

<code>!Version,x</code> selects the DynamicInfo palette: 0 for the first, 1 for the second. <code>!PaletteOption,x</code> uses <code>EPPP----</code>: E enables the global effect, and PPP selects palette 8–F manually or a search group automatically. In automatic mode, <code>000</code> allows all, nonzero <code>0XX</code> allows 8–B, and <code>1XX</code> allows C–F.

<code>!PaletteAssignmentOption,x</code> uses <code>--AA----</code>: <code>$00</code> selects the destination automatically, <code>$10</code> uses PPP, and <code>$20</code> uses existing level colors. To prepare a palette for a later local effect, use a mode that reads DynamicInfo colors: automatic or manual with upload.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalPaletteAssignmentNoUpload()</code>.
* Cluster sprite: <code>%DXClusterPaletteAssignmentNoUpload()</code>.
* Extended sprite: <code>%DXExtendedPaletteAssignmentNoUpload()</code>.

'''Inputs'''

* 16-bit A: <code>!MySpritePaletteTableOffset</code> for the DynamicInfo containing the palettes.
* X: sprite index.
* <code>!Version,x</code>, <code>!PaletteOption,x</code>, and <code>!PaletteAssignmentOption,x</code>: same options as <code>!PaletteAssignment</code>.
* <code>!LastVersion,x</code>: last processed version, compared with <code>!Version,x</code> to detect changes. Initialize to <code>$FF</code>.

'''Result'''

* Carry set: a palette is assigned; clear if one could not be obtained.
* <code>!Palette,x</code>: assigned palette.
* <code>!LastVersion,x</code>: updated to <code>!Version,x</code> when the new assignment is processed.
* <code>$00-$01</code>: ID of the selected DynamicInfo palette when using a mode that loads its colors.
* <code>$02-$04</code>: base palette ROM address.
* Y = 1: palette newly assigned and effect must be calculated; Y = 0: no recalculation needed due to a new assignment. Pass this value to the concatenation routine.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

; Prepare and concatenate the effect here.
; Preserve Y and the $02-$04 address for that call.
.Return
RTS
</pre>

<code>$00-$01</code> identifies the chosen DynamicInfo palette; <code>!Palette,x</code> identifies the sprite palette 8–F used for drawing. <code>$00-$04</code> is prepared only when the routine reads DynamicInfo. Do not treat it as output in manual-without-upload mode, with palette changes disabled, or when the current game mode does not process the call.

<code>!MySpritePaletteTableOffset</code> is generated from DynamicInfo and stored in <code>DXDefines.asm</code>. PascalCase normalization removes separators: <code>my_sprite</code> becomes <code>MySprite</code>.

=== Upload ===

<code>!Upload</code> makes the graphics for the sprite's current pose available for drawing. It selects the pose by adding <code>!PoseIndex,x</code> to the dynamic pose ID in A. If the graphics are already in VRAM, it updates their last-use record to protect them from replacement. Otherwise, it requests an upload. Call it every frame in the long routine.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalUpload()</code>.
* Cluster sprite: <code>%DXClusterUpload()</code>.
* Extended sprite: <code>%DXExtendedUpload()</code>.

'''Inputs'''

* 16-bit A: base dynamic pose ID.
* X: sprite index.
* <code>!PoseIndex,x</code>: index added to the base ID.
* <code>!GlobalFlip,x</code> and <code>!LocalFlip,x</code>: flip settings combined when drawing the pose.

'''Result'''

* Carry set: the sprite has a pose it can draw. This may be the requested pose or the previous one if the new pose could not be uploaded yet.
* Carry clear: the sprite does not have a pose it can draw yet.
* <code>!LastPoseIndex,x</code>, <code>!LastPoseHashIndex,x</code>, and <code>!LastFlip,x</code>: state of the pose available for drawing.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
!Upload
RTS
</pre>

<code>!DynamicPoseIDMySprite000</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase: separators are removed and each word starts with a capital letter, as in <code>my_sprite</code> → <code>MySprite</code>.

=== UploadWithoutPoseOffset ===

<code>!UploadWithoutPoseOffset</code> requests the exact dynamic pose ID in A, without adding <code>!PoseIndex</code>. Like <code>!Upload</code>, it reuses graphics already in VRAM and can keep the previous pose available until the new one can be uploaded.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalUploadWithoutPoseOffset()</code>.
* Cluster sprite: <code>%DXClusterUploadWithoutPoseOffset()</code>.
* Extended sprite: <code>%DXExtendedUploadWithoutPoseOffset()</code> exists, but <code>ExtendedSpriteDefines.asm</code> currently does not provide the <code>!UploadWithoutPoseOffset</code> alias.

'''Inputs'''

* 16-bit A: exact dynamic pose ID.
* X: sprite index.
* <code>!GlobalFlip,x</code> and <code>!LocalFlip,x</code>: sprite flip settings.

'''Result'''

* Carry set: the sprite has a pose it can draw. Carry clear: no pose is available yet.
* Stores the pose available for drawing in <code>!LastPoseIndex,x</code> and its graphics location in <code>!LastPoseHashIndex,x</code>, just like <code>!Upload</code>.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite003
!UploadWithoutPoseOffset
RTS
</pre>

<code>!DynamicPoseIDMySprite003</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names use PascalCase, with separators removed: <code>my_sprite</code> becomes <code>MySprite</code>.

=== DXDraw ===

<code>!DXDraw</code> draws a pose using the dynamic graphics available to the sprite.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalDraw()</code>.
* Cluster sprite: <code>%DXClusterDraw()</code>.
* Extended sprite: <code>%DXExtendedDraw()</code>.

'''Inputs'''

* 16-bit A: drawing pose ID.
* X: sprite index.
* <code>!PropParam</code> (<code>$52</code>): additional properties in <code>YXCC----</code> format.
* <code>!MaxTilePriorityParam</code> (<code>$0A</code>): maximum tile priority; <code>$00</code> highest, <code>$01</code> high, <code>$02</code> the sprite type's own priority, and <code>$03</code> lowest.
* <code>!Palette,x</code>, <code>!LastFlip,x</code>, and <code>!LastPoseHashIndex,x</code>: palette, flip settings, and location of the available graphics.

'''Result'''

Draws the pose on screen. If <code>!LastPoseHashIndex,x</code> is <code>$FF</code>, nothing is drawn. A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
Draw:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDraw
RTS
</pre>

In this example, the poses must appear in the same order in the DrawInfo and DynamicInfo. <code>!LastPoseIndex</code> identifies the pose that can actually be drawn: if the new pose could not be uploaded yet, the previous one is drawn instead.

<code>!PoseIDMySprite_Frame0</code> is generated from the DrawInfo and written to <code>DXDefines.asm</code>. Resource and pose names are normalized to PascalCase by removing separators, as in <code>my_sprite</code> → <code>MySprite</code>. This drawing ID is separate from the DynamicInfo's <code>!DynamicPoseID...</code> IDs.

=== DXDrawWithOffset ===

<code>!DXDrawWithOffset</code> draws the pose a few pixels to the right, left, above, or below the sprite's position. This only changes where the pose is drawn; movement and collision still use the sprite's original position.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalDrawWithOffset()</code>.
* Cluster sprite: <code>%DXClusterDrawWithOffset()</code>.
* Extended sprite: <code>%DXExtendedDrawWithOffset()</code>.

'''Inputs'''

* The same inputs as <code>!DXDraw</code>.
* <code>!XOffsetParam</code> (<code>$8A</code>): signed 8-bit horizontal offset.
* <code>!YOffsetParam</code> (<code>$8B</code>): signed 8-bit vertical offset.

'''Result'''

Draws the pose like <code>!DXDraw</code>, with the specified offsets added. A positive <code>!XOffsetParam</code> moves the drawing to the right, and a positive <code>!YOffsetParam</code> moves it down. Negative values move it left or up.

'''Example'''

<pre>
Draw:
LDA #$08
STA !XOffsetParam
LDA #$F8
STA !YOffsetParam
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDrawWithOffset
RTS
</pre>

The example draws the pose 8 pixels to the right and 8 pixels up. <code>!PoseIDMySprite_Frame0</code> is generated from the DrawInfo and written to <code>DXDefines.asm</code>; names are normalized to PascalCase by removing separators, as in <code>my_sprite</code> → <code>MySprite</code>.

=== ReplacePalette ===

<code>!ReplacePalette</code> changes the colors of the sprite's assigned palette without changing its assignment ID. For example, it can replace the normal palette during a special state. If other sprites share that palette, their colors change too. Call it when the colors need to change; calling it every frame makes the system prepare the palette and its effects again each time.

It is commonly used after <code>!PaletteAssignmentNoUpload</code>: assign the palette without uploading its colors, then replace them with the colors you want. Before calling <code>!ReplacePalette</code>, put the address of the new colors in <code>$02-$04</code>.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalReplacePalette()</code>.
* Cluster sprite: <code>%DXClusterReplacePalette()</code>.
* Extended sprite: <code>%DXExtendedReplacePalette()</code>.

'''Inputs'''

* X: sprite index.
* A in 8-bit mode.
* <code>$02-$04</code>: ROM address of the new palette in BGR555 format.
* <code>!Palette,x</code>: the assigned palette.
* <code>!PaletteOption,x</code>: whether the palette is affected by the global effect.

'''Result'''

* Carry set: the palette is ready for drawing. If the new colors are not ready yet, the previous colors remain available.
* Carry clear: the palette has no colors ready for drawing yet.

Keeps the same palette ID and requests a change to its colors. When marking the effect for recalculation, it uses <code>$FFFF</code> if no colors have ever been ready for drawing, or <code>$FFFE</code> if the previous colors can still be used while the new ones are prepared.

'''Example'''

<pre>
ReplaceSpritePalette:
; Run when an assigned palette needs new colors.
LDA.b #!PaletteMyAlternatePalette
STA $02
LDA.b #!PaletteMyAlternatePalette>>8
STA $03
LDA.b #!PaletteMyAlternatePalette>>16
STA $04
!ReplacePalette
RTS
</pre>

<code>!PaletteMyAlternatePalette</code> is the address of a palette inserted from the resources declared in a DynamicInfo. It is written to <code>DXDefines.asm</code>. Its name is normalized to PascalCase: <code>my_alternate_palette</code> becomes <code>MyAlternatePalette</code>.

=== ConcatenateRGBPaletteEffectToGlobal ===

<code>!ConcatenateRGBPaletteEffectToGlobal</code> lets the sprite's palette use its own RGB effect while still being affected by the global effect. It applies the local effect, such as <code>PaletteTransitionRGB</code>, first, then applies the global effect to that result. Call it after <code>!PaletteAssignmentNoUpload</code>, which prepares the original palette.

The usual sequence is to assign the palette with <code>!PaletteAssignmentNoUpload</code>, check that carry is set, then call this routine to apply the effects and finish uploading the colors.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalConcatenateRGBPaletteEffectToGlobal()</code>.
* Cluster sprite: <code>%DXClusterConcatenateRGBPaletteEffectToGlobal()</code>.
* Extended sprite: <code>%DXExtendedConcatenateRGBPaletteEffectToGlobal()</code>.

'''Inputs'''

* 16-bit A: local RGB effect ID.
* 8-bit X: copy the value of <code>!Palette,x</code> here using <code>LDA !Palette,x</code> followed by <code>TAX</code>, as shown in the example.
* 8-bit Y: keep the value returned by <code>!PaletteAssignmentNoUpload</code>. A value of 1 forces the effect to be recalculated; 0 allows the previous result to be reused if nothing has changed.
* <code>$02-$04</code>: BGR555 base palette address prepared by palette assignment.
* <code>!PaletteOption</code>: the <code>E</code> bit must be set to combine the local effect with the global effect.

'''Result'''

* Carry set: the palette can be used for drawing. If the new effect is not ready yet, the previous result remains in use.
* Carry clear: the palette has no colors ready for drawing yet.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

LDA !Palette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyRGBEffect0
!ConcatenateRGBPaletteEffectToGlobal
.Return
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> is generated from the DynamicInfo, and <code>!PaletteEffectIDMyRGBEffect0</code> from a <code>*.paleffect</code> file. Both are written to <code>DXDefines.asm</code>. Names are normalized to PascalCase by removing separators, as in <code>my_sprite</code> → <code>MySprite</code>. If you use Y to select an effect from a table, save it with <code>PHY</code> and restore it with <code>PLY</code> before calling the concatenation routine.

=== ConcatenateHSLPaletteEffectToGlobal ===

<code>!ConcatenateHSLPaletteEffectToGlobal</code> lets the sprite's palette use its own HSL effect, such as <code>MixH</code>, while still being affected by the global effect. It applies the local effect first, followed by the global effect. Call it after <code>!PaletteAssignmentNoUpload</code>, which prepares the original palette.

The usual sequence is to assign the palette with <code>!PaletteAssignmentNoUpload</code>, check that carry is set, then call this routine to apply the effects and finish uploading the colors.

'''Routine used by sprite type'''

* Normal sprite: <code>%DXNormalConcatenateHSLPaletteEffectToGlobal()</code>.
* Cluster sprite: <code>%DXClusterConcatenateHSLPaletteEffectToGlobal()</code>.
* Extended sprite: <code>%DXExtendedConcatenateHSLPaletteEffectToGlobal()</code>.

'''Inputs'''

* 16-bit A: local HSL effect ID.
* 8-bit X: copy the value of <code>!Palette,x</code> here using <code>LDA !Palette,x</code> followed by <code>TAX</code>, as shown in the example.
* 8-bit Y: keep the value returned by <code>!PaletteAssignmentNoUpload</code>. A value of 1 forces the effect to be recalculated; 0 allows the previous result to be reused if nothing has changed.
* <code>$02-$04</code>: BGR555 base palette address prepared by palette assignment.
* <code>!PaletteOption</code>: the <code>E</code> bit must be set to combine the local effect with the global effect.

'''Result'''

* Carry set: the palette can be used for drawing. If the new effect is not ready yet, the previous result remains in use.
* Carry clear: the palette has no colors ready for drawing yet.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

LDA !Palette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyHSLEffect0
!ConcatenateHSLPaletteEffectToGlobal
.Return
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> is generated from the DynamicInfo, and <code>!PaletteEffectIDMyHSLEffect0</code> from a <code>*.paleffect</code> file. Both are written to <code>DXDefines.asm</code>. Names are normalized to PascalCase: separators are removed and each word starts with a capital letter. Save and restore Y with <code>PHY</code>/<code>PLY</code> if you temporarily use it to select an effect.

Both concatenation variants handle the required conversions when the local and global effects use different color spaces. See [[Dynamic_Xtreme_files_and_formats#Effect_types|Effect types]] to find out which effects use RGB or HSL.

== General Routines and Macros ==

These routines and macros let sprites, UberASM, and other code use Dynamic Xtreme's systems. Macro arguments specify the variables and values to use. If an argument contains a comma, such as <code>!NormalPoseIndex,x</code>, put it in quotation marks so Asar reads it as a single argument. Use <code>#</code> for immediate values, such as <code>#$04</code>.

The rules for [[#CPU_state_and_temporary_memory|DBR, direct page, flags, and the stack]] also apply here. Each family's calling requirements explain which registers and temporary memory you must save if you need to preserve them.

=== Calls and returns at a glance ===

Some macros include the return instruction that ends the routine containing them. In those cases, code written after the macro does not run as a continuation of that routine.

{| class="wikitable"
! Call or family !! Included return !! Usage
|-
| Sprite aliases: <code>!RenderBox</code>, <code>!Upload</code>, <code>!DXDraw</code>, <code>!PaletteAssignment</code>, and the other aliases in this category.
| The call returns and execution continues after the alias.
| Write the alias directly, without <code>JSR</code> or <code>JSL</code>. Your routine still needs its own return instruction.
|-
| [[#GeneralUpload|GeneralUpload]], [[#Upload_(general_macro)|Upload (general macro)]], and [[#StandardSpriteUpload|StandardSpriteUpload]].
| <code>RTS</code>.
| Place the macro at the end of a routine called with <code>JSR</code>.
|-
| [[#Draw|Draw]], [[#StandardSpriteDraw|StandardSpriteDraw]], and [[#DrawStatic|DrawStatic]].
| <code>RTS</code>.
| Place the macro at the end of a routine called with <code>JSR</code>.
|-
| [[#PaletteAssignment_(general_macro)|PaletteAssignment]], [[#PaletteAssignmentNoUpload_(general_macro)|PaletteAssignmentNoUpload]], [[#StandardSpritePaletteAssignment|StandardSpritePaletteAssignment]], and [[#StandardSpritePaletteAssignmentNoUpload|StandardSpritePaletteAssignmentNoUpload]].
| <code>RTL</code>.
| Place the macro at the end of a routine called with <code>JSL</code>.
|-
| The general macro versions of [[#ReplacePalette_(general_macro)|ReplacePalette]] and [[#Combining_a_local_effect_with_the_global_effect|ConcatenateRGBPaletteEffectToGlobal and ConcatenateHSLPaletteEffectToGlobal]].
| <code>RTL</code>.
| Place the macro at the end of a routine called with <code>JSL</code>.
|-
| [[#LoadPaletteIDAndAddress|LoadPaletteIDAndAddress]] and [[#DefineDynamicSpaceConfig|DefineDynamicSpaceConfig]].
| None: execution continues after the macro.
| You can write more code after the macro. Your routine needs its own return instruction.
|-
| [[#Uploading_colors_with_TransferPalette|TransferPaletteFromAddress, FromPointer, FromTable, Resource, and ResourceWithLength]].
| None: execution continues after the macro.
| Check carry after the macro, then continue or return according to the result.
|-
| [[#Palette_effects|Base preparation, mixing, transition, DoEffect, and conversion]] macros, including their <code>Default</code> variants.
| None: execution continues after the macro.
| You can chain more operations after the macro. The two concatenation macros are the exceptions listed above.
|-
| [[#PPU|VRAM and CGRAM transfer]] macros, including <code>Forced</code> variants, and [[#Math|math]] macros.
| None: execution continues after the macro.
| Your routine needs its own return instruction.
|-
| Patch routines [[#DynamicPoseSpaceConfig|DynamicPoseSpaceConfig]], [[#TakeDynamicRequest|TakeDynamicRequest]], and [[#DynamicRoutine|DynamicRoutine]].
| The called routine returns with <code>RTL</code>.
| Use <code>JSL !NombreDeLaRutina</code>. On return, execution resumes at the instruction after <code>JSL</code>; your routine still needs its own return instruction.
|}

For example, a routine containing <code>%Upload(...)</code> is called with <code>JSR PoseManagement</code> and ends with the macro's own <code>RTS</code>. A routine containing <code>%PaletteAssignment(...)</code> is called with <code>JSL PaletteManagement</code> and ends with its <code>RTL</code>. The <code>!Upload</code> alias works differently: it calls a shared PIXI routine and allows execution to continue afterward, rather than expanding <code>%Upload(...)</code> directly.

=== Dynamic poses ===

==== DynamicPoseSpaceConfig ====

'''Registers and temporary memory:''' enter with A, X, and Y in 8-bit mode. Modifies A and X; preserves Y and register sizes. Uses no scratch memory. Saves and restores DBR around configuration selection. Does not return a result in carry. Called with <code>JSL</code>; returns with <code>RTL</code>.

<code>JSL !DynamicPoseSpaceConfig</code> selects the parts of graphics memory (VRAM) that Dynamic Xtreme can use for dynamic poses. It is normally called from UberASM's <code>init</code> when entering a level.

The available configurations are defined in <code>DXDefines.asm</code> under names beginning with <code>!DynamicSpaceConfig...</code>.

'''Input'''

* 8-bit A: one of the <code>!DynamicSpaceConfig...</code> configurations in <code>DXDefines.asm</code>. Values range from <code>$00</code> to <code>$1C</code>.

'''Result'''

After this call, Dynamic Xtreme can only place new poses in the selected regions. Changing the configuration does not remove poses already in VRAM. It is normally set when entering the level, before sprites request their graphics.

'''Example'''

<pre>
init:
LDA #!DynamicSpaceConfigSP4
JSL !DynamicPoseSpaceConfig
RTL
</pre>

<code>!DynamicSpaceConfigSP4</code> is a constant in <code>DXDefines.asm</code> that enables SP4. Other options include <code>!DynamicSpaceConfigSP3</code>, <code>!DynamicSpaceConfigSP34</code>, and <code>!DynamicSpaceConfigSP234</code>. Choose a region that does not overlap the level's static graphics.

==== DefineDynamicSpaceConfig ====

<code>%DefineDynamicSpaceConfig()</code> specifies which VRAM regions can hold dynamic poses and which are restricted. Use it to create your own configuration instead of selecting a preset with <code>!DynamicPoseSpaceConfig</code>.

'''Parameters'''

<pre>
%DefineDynamicSpaceConfig(init, end, restricted)
</pre>

* <code>init</code>: ID of the region's first 16×16 block.
* <code>end</code>: ID of the region's last 16×16 block. Both endpoints are included.
* <code>restricted</code>: <code>$00</code> allows dynamic poses in this region; <code>$80</code> restricts it, preventing the system from placing poses there.

All three parameters are assembly-time constants and are written without <code>#</code>. The first block must be less than or equal to the last, and both must be between <code>$00</code> and <code>$7F</code>. For example, <code>$60</code> through <code>$7F</code> covers 32 blocks.

'''Block numbering'''

For this configuration, sprite graphics memory is treated as a '''128×256-pixel''' grid. The upper 128×128 half corresponds to SP1 and SP2; the lower 128×128 half corresponds to SP3 and SP4.

The grid is divided into 16×16 blocks: '''8 blocks per row and 16 rows''', for a total of 128 blocks. IDs run from left to right, continuing on the next row from top to bottom:

{| class="wikitable"
! Row of 16×16 tiles !! Col. 0 !! Col. 1 !! Col. 2 !! Col. 3 !! Col. 4 !! Col. 5 !! Col. 6 !! Col. 7
|-
! 0
| <code>$00</code> || <code>$01</code> || <code>$02</code> || <code>$03</code> || <code>$04</code> || <code>$05</code> || <code>$06</code> || <code>$07</code>
|-
! 1
| <code>$08</code> || <code>$09</code> || <code>$0A</code> || <code>$0B</code> || <code>$0C</code> || <code>$0D</code> || <code>$0E</code> || <code>$0F</code>
|-
! 2
| <code>$10</code> || <code>$11</code> || <code>$12</code> || <code>$13</code> || <code>$14</code> || <code>$15</code> || <code>$16</code> || <code>$17</code>
|-
! 3
| <code>$18</code> || <code>$19</code> || <code>$1A</code> || <code>$1B</code> || <code>$1C</code> || <code>$1D</code> || <code>$1E</code> || <code>$1F</code>
|-
! 4
| <code>$20</code> || <code>$21</code> || <code>$22</code> || <code>$23</code> || <code>$24</code> || <code>$25</code> || <code>$26</code> || <code>$27</code>
|-
! 5
| <code>$28</code> || <code>$29</code> || <code>$2A</code> || <code>$2B</code> || <code>$2C</code> || <code>$2D</code> || <code>$2E</code> || <code>$2F</code>
|-
! 6
| <code>$30</code> || <code>$31</code> || <code>$32</code> || <code>$33</code> || <code>$34</code> || <code>$35</code> || <code>$36</code> || <code>$37</code>
|-
! 7
| <code>$38</code> || <code>$39</code> || <code>$3A</code> || <code>$3B</code> || <code>$3C</code> || <code>$3D</code> || <code>$3E</code> || <code>$3F</code>
|-
! 8
| <code>$40</code> || <code>$41</code> || <code>$42</code> || <code>$43</code> || <code>$44</code> || <code>$45</code> || <code>$46</code> || <code>$47</code>
|-
! 9
| <code>$48</code> || <code>$49</code> || <code>$4A</code> || <code>$4B</code> || <code>$4C</code> || <code>$4D</code> || <code>$4E</code> || <code>$4F</code>
|-
! 10
| <code>$50</code> || <code>$51</code> || <code>$52</code> || <code>$53</code> || <code>$54</code> || <code>$55</code> || <code>$56</code> || <code>$57</code>
|-
! 11
| <code>$58</code> || <code>$59</code> || <code>$5A</code> || <code>$5B</code> || <code>$5C</code> || <code>$5D</code> || <code>$5E</code> || <code>$5F</code>
|-
! 12
| <code>$60</code> || <code>$61</code> || <code>$62</code> || <code>$63</code> || <code>$64</code> || <code>$65</code> || <code>$66</code> || <code>$67</code>
|-
! 13
| <code>$68</code> || <code>$69</code> || <code>$6A</code> || <code>$6B</code> || <code>$6C</code> || <code>$6D</code> || <code>$6E</code> || <code>$6F</code>
|-
! 14
| <code>$70</code> || <code>$71</code> || <code>$72</code> || <code>$73</code> || <code>$74</code> || <code>$75</code> || <code>$76</code> || <code>$77</code>
|-
! 15
| <code>$78</code> || <code>$79</code> || <code>$7A</code> || <code>$7B</code> || <code>$7C</code> || <code>$7D</code> || <code>$7E</code> || <code>$7F</code>
|}

Each cell represents a 16×16 tile and contains its block ID. Rows are numbered 0–15 and columns 0–7. These IDs are separate from the 8×8 TileCodes used in DrawInfo.

{| class="wikitable"
! Section !! Blocks !! Position in the grid
|-
| SP1 || <code>$00–$1F</code> || First four rows.
|-
| SP2 || <code>$20–$3F</code> || Next four rows.
|-
| SP3 || <code>$40–$5F</code> || Next four rows.
|-
| SP4 || <code>$60–$7F</code> || Last four rows.
|}

'''Examples from the patch'''

These configurations use the same ranges as the patch's presets. Place them in UberASM's <code>init</code>, before sprites request their poses.

'''Use SP4 only:'''

<pre>
init:
; Restrict SP1, SP2, and SP3.
%DefineDynamicSpaceConfig($00, $5F, $80)

; Make SP4 available for dynamic poses.
%DefineDynamicSpaceConfig($60, $7F, $00)
RTL
</pre>

'''Use SP3 only:'''

<pre>
init:
; Restrict SP1 and SP2.
%DefineDynamicSpaceConfig($00, $3F, $80)

; Make SP3 available for dynamic poses.
%DefineDynamicSpaceConfig($40, $5F, $00)

; Restrict SP4.
%DefineDynamicSpaceConfig($60, $7F, $80)
RTL
</pre>

'''Use SP3 and SP4:'''

<pre>
init:
; Restrict SP1 and SP2.
%DefineDynamicSpaceConfig($00, $3F, $80)

; Make SP3 and SP4 available as a single region.
%DefineDynamicSpaceConfig($40, $7F, $00)
RTL
</pre>

Each example is an alternative configuration. Use one complete configuration covering blocks <code>$00–$7F</code> with consecutive, non-overlapping regions. Restrict any blocks used by the player, static sprites, or other resources whose graphics must stay in place. The macro does not detect those uses for you.

'''Registers and result'''

* A must be in 8-bit mode. The macro modifies A and the N/Z flags; it preserves X, Y, carry, DBR, and D, and does not change register sizes.
* Writes the configuration to <code>DX_Dynamic_Tile_Size</code> and <code>DX_Dynamic_Tile_Offset</code> at both ends of the specified region. Uses no scratch memory.
* Does not upload graphics or move poses already in VRAM. Use it to configure the available space when entering the level.
* Does not report success or failure in carry, and includes neither <code>RTS</code> nor <code>RTL</code>: execution continues after each call. The <code>RTL</code> in the examples ends UberASM's <code>init</code>.

==== TakeDynamicRequest ====

'''Registers and temporary memory:''' enter with 8-bit A and 16-bit X/Y. A, X, and Y return in 8-bit mode; their values may change. X is a valid cache entry index only when carry is set; it does not preserve the sprite index. May overwrite <code>$00-$0F</code> and <code>$47-$51</code> when preparing a new upload. Preserves DBR and D on both success and failure. Called with <code>JSL</code>; returns with <code>RTL</code>.

<code>JSL !TakeDynamicRequest</code> takes a pose ID and looks for its graphics in VRAM. If they are already loaded, it marks them as in use to protect them from replacement. Otherwise, it finds space and schedules an upload for the next NMI, when the game updates graphics between frames.

'''Input'''

* 16-bit Y: exact dynamic pose ID.

'''Result'''

* Carry set: the graphics are already in VRAM or their upload has been scheduled for the next NMI. X contains the cache entry index that records their location.
* Carry clear: there is not enough VRAM space, or uploading the pose would exceed the frame's transfer limit.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
RequestPose:
REP #$10
LDY #!DynamicPoseIDMySprite000
JSL !TakeDynamicRequest
BCC .Unavailable

; X contains the requested pose's hash table index.
; Your code can save this index to draw the pose.
RTS
.Unavailable
; Handle unavailable resources here.
RTS
</pre>

<code>!DynamicPoseIDMySprite000</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase by removing separators and capitalizing each word: <code>my_sprite</code> becomes <code>MySprite</code>.

This call returns the cache entry that records the graphics location, but does not store it in the sprite's variables or fall back to the previous pose if the request fails. Use <code>!Upload</code> for that complete behavior.

==== DynamicRoutine ====

'''Registers and temporary memory:''' sets A, X, and Y to 16-bit mode for its calculations and leaves them in 8-bit mode on return. All three values may change. May overwrite <code>$00-$0B</code> and <code>$47-$51</code>; <code>PoseIDBackup</code> occupies <code>$02-$03</code> in direct page. Preserves D and does not change DBR: set the tables' data bank before calling it. Called with <code>JSL</code>; returns with <code>RTL</code>.

<code>JSL !DynamicRoutine</code> queues an upload of a pose's graphics to a specific VRAM location. The transfer takes place during NMI.

The routine needs to know which pose to copy and where to place it. It receives the destination in A, but reads the pose ID from an internal variable called <code>PoseIDBackup</code>. <code>!TakeDynamicRequest</code> prepares these values before calling it.

'''Required inputs'''

* Low 8 bits of A: starting block in the dynamic system's VRAM map. The routine converts this value into a VRAM address.
* <code>PoseIDBackup</code>: internal 16-bit variable containing the ID of the pose to copy.
* DBR (Data Bank Register): must select the bank containing the pose address and size tables.

Before calling this routine, your code must have allocated enough VRAM space and checked that the upload fits within the frame's byte limit. <code>!TakeDynamicRequest</code> handles both tasks.

'''Result'''

Reads the address and amount of graphics data for the pose, calculates how to place it at the destination, and adds the required transfers to the VRAM queue. A, X, and Y return in 8-bit mode. Carry does not report success or failure.

'''How it works'''

When a sprite requests a pose that is not yet in VRAM, <code>!TakeDynamicRequest</code> finds a place for it. It then stores the ID in <code>PoseIDBackup</code> and calls <code>!DynamicRoutine</code> with the selected position in A. <code>!DynamicRoutine</code> prepares the graphics transfer; NMI performs it.

Use <code>!Upload</code> to load a pose from sprite code. Use <code>!TakeDynamicRequest</code> to request one directly by ID. Calling <code>!DynamicRoutine</code> also requires you to prepare the internal pose ID, data bank, and destination space described above.

==== GeneralUpload ====

'''Registers and temporary memory:''' enter with 16-bit A and 8-bit X/Y. A, X, and Y return in 8-bit mode. A and Y may change; with <code>sprite = 1</code> or <code>2</code>, X is restored from <code>!SpriteIndex</code>; with <code>sprite = 0</code>, X is not preserved. May overwrite <code>$00-$0F</code> and <code>$47-$51</code>, including temporary values used for a new request. Preserves DBR and D. Includes <code>RTS</code>: use <code>JSR</code> to call the routine containing the macro.

<code>%GeneralUpload()</code> handles pose uploads like the sprite routines, but lets you choose the variables used to store the pose index, flip settings, and graphics location. This is useful for an entity with several independent poses, or for code that uses its own tables.

'''Parameters'''

<pre>
%GeneralUpload(Pose16, checkLast, sprite, flip, safeCheck, withoutOffset,
safeLow, safeHigh, poseIndex, lastPoseIndex, lastPoseHashIndex,
globalFlip, localFlip, lastFlip)
</pre>

The signature above shows the parameter order; write the actual call on one line.

* <code>Pose16</code>: 0 uses 8-bit pose indices; 1 uses 16-bit indices.
* <code>checkLast</code>: 1 keeps the previous pose available if the new one cannot be obtained; 0 disables this fallback.
* <code>sprite</code>: 0 uses your own variables without restoring the sprite index; 1 uses sprite tables and restores X from <code>!SpriteIndex</code>; 2 works like 1, but requests the pose without comparing or updating <code>lastPoseIndex</code>.
* <code>flip</code>: 1 combines <code>globalFlip</code> and <code>localFlip</code> into <code>lastFlip</code>; 0 skips this update.
* <code>safeCheck</code>: 1 uses <code>safeLow</code> and <code>safeHigh</code> to prevent duplicate requests in the same frame; 0 skips this check.
* <code>withoutOffset</code>: 0 adds <code>poseIndex</code> to the base ID; 1 uses the supplied ID directly.
* <code>safeLow</code> and <code>safeHigh</code>: variables holding the low and high bytes of the request's frame number. They are written even when <code>safeCheck</code> is 0.
* <code>poseIndex</code>: variable holding the desired pose index.
* <code>lastPoseIndex</code>: variable holding the last available pose index.
* <code>lastPoseHashIndex</code>: variable identifying the entry where Dynamic Xtreme records the graphics location in VRAM. <code>$FF</code> means no graphics are available yet.
* <code>globalFlip</code>, <code>localFlip</code>, and <code>lastFlip</code>: global, local, and combined flip variables.

'''Additional input'''

* 16-bit A: base or exact dynamic pose ID, depending on <code>withoutOffset</code>.
* With <code>sprite = 1</code> or <code>sprite = 2</code>, <code>!SpriteIndex</code> must contain the sprite index.

With <code>sprite = 2</code>, the macro requests the pose even when <code>poseIndex</code> equals <code>lastPoseIndex</code>, and leaves <code>lastPoseIndex</code> unchanged. If it obtains the graphics, it stores their location in <code>lastPoseHashIndex</code>. If the request fails and <code>checkLast</code> is 1, the previous graphics can still be used. <code>safeCheck</code> still controls whether another request is allowed in the same frame.

The value 2 does not change the index size. Select <code>Pose16 = 1</code> to use 16-bit index variables. The dynamic pose ID supplied in A is always 16-bit.

<code>sprite = 2</code> is commonly used for dynamic sprites with several parts, such as a head and body whose graphics must change together. By leaving <code>lastPoseIndex</code> unchanged, it lets the sprite code coordinate all parts before updating the pose index. The macro does not synchronize the parts itself; the calling code handles that.

'''Result'''

Returns carry set when a pose is available for drawing: either the requested pose or the previous one if <code>checkLast</code> allows it. Returns carry clear if neither is available. Stores the pose's state in the supplied variables and marks its graphics as in use to protect them from replacement. The macro ends with <code>RTS</code>; place it at the end of a routine called with <code>JSR</code>.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%GeneralUpload(0, 1, 1, 1, 1, 0, "!NormalSafeFrameLowByte,x", "!NormalSafeFrameHighByte,x", "!NormalPoseIndex,x", "!NormalLastPoseIndex,x", "!NormalLastPoseHashIndex,x", "!NormalGlobalFlip,x", "!NormalLocalFlip,x", "!NormalLastFlip,x")
</pre>

The example uses normal sprite tables and an 8-bit pose index. <code>!DynamicPoseIDMySprite000</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>; names are normalized to PascalCase by removing separators, as in <code>my_sprite</code> → <code>MySprite</code>.

==== Upload (general macro) ====

'''Registers and temporary memory:''' follows the same requirements as [[#GeneralUpload|GeneralUpload]], with <code>Pose16 = 0</code>. Enter with 16-bit A and 8-bit X/Y; all three return in 8-bit mode. The <code>sprite</code> parameter determines whether X is reloaded from <code>!SpriteIndex</code>. The macro includes <code>RTS</code>.

<code>%Upload()</code> is the 8-bit pose index variant of <code>%GeneralUpload()</code>. It is separate from the sprite alias <code>!Upload</code>.

'''Parameters'''

<pre>
%Upload(sprite, checkLast, flip, safeCheck, withoutOffset,
safeLow, safeHigh, poseIndex, lastPoseIndex, lastPoseHashIndex,
globalFlip, localFlip, lastFlip)
</pre>

Takes the same inputs as <code>%GeneralUpload()</code>, but indices stored in variables are always 8-bit. The macro includes the <code>RTS</code> that ends the routine.

The <code>sprite</code> parameter also accepts 2: this skips the comparison with <code>lastPoseIndex</code> and leaves that variable unchanged, but still updates <code>lastPoseHashIndex</code> when the pose is obtained. It does not enable 16-bit indices; use <code>%GeneralUpload()</code> with <code>Pose16 = 1</code> for those.

This mode is commonly used to make several parts of a dynamic sprite change their graphics together. For example, your code can handle head and body uploads separately, then update the pose index when both parts should change. Leaving <code>lastPoseIndex</code> unchanged lets the sprite code control that change.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%Upload(1, 1, 1, 1, 0, "!NormalSafeFrameLowByte,x", "!NormalSafeFrameHighByte,x", "!NormalPoseIndex,x", "!NormalLastPoseIndex,x", "!NormalLastPoseHashIndex,x", "!NormalGlobalFlip,x", "!NormalLocalFlip,x", "!NormalLastFlip,x")
</pre>

<code>!DynamicPoseIDMySprite000</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names use PascalCase, with separators removed: <code>my_sprite</code> becomes <code>MySprite</code>.

==== StandardSpriteUpload ====

'''Registers and temporary memory:''' follows [[#GeneralUpload|GeneralUpload]] with <code>sprite = 1</code>. Enter with 16-bit A and 8-bit X/Y. On return, X contains <code>!SpriteIndex</code>; A and Y may change, and all three are in 8-bit mode. Uses the same scratch memory and ends with <code>RTS</code>.

<code>%StandardSpriteUpload(withoutOffset, type)</code> automatically selects the Dynamic Xtreme tables for a normal, cluster, or extended sprite. PIXI's upload routines use this macro.

'''Parameters and inputs'''

* <code>withoutOffset</code>: 0 adds <code>!PoseIndex</code> to the base ID; 1 uses the exact ID.
* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code>, or <code>"Extended"</code>.
* 16-bit A: dynamic pose ID.
* <code>!SpriteIndex</code>: sprite index.
* Dynamic Xtreme pose and flip tables for the selected sprite type, initialized as described for <code>!Upload</code>.

'''Result'''

Selects the variables for the specified sprite type. Keeps the previous pose available if the new one is not ready, updates flip settings, and prevents duplicate requests in the same frame. Carry works as it does for <code>!Upload</code>. The macro includes the <code>RTS</code> that ends the routine.

'''Example'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%StandardSpriteUpload(0, "Normal")
</pre>

<code>!DynamicPoseIDMySprite000</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase: <code>my_sprite</code> becomes <code>MySprite</code>, with separators removed.

=== Pose drawing ===

Macros in this category end the routine containing them with <code>RTS</code>. Call the example routines with <code>JSR</code>. A must hold the 16-bit drawing pose ID; prepare <code>!PropParam</code> (<code>$52</code>) and <code>!MaxTilePriorityParam</code> (<code>$0A</code>) as described for <code>!DXDraw</code>.

==== Draw ====

'''Registers and temporary memory:''' enter with 16-bit A and 8-bit X/Y. A and Y may change. With <code>sprite = 1</code>, X is restored from <code>!SpriteIndex</code> when preparing a valid pose; with <code>sprite = 0</code>, the original X is not preserved. If no valid pose is available, X is unchanged. All three return in 8-bit mode. May overwrite <code>$00-$0F</code>, <code>$45-$4F</code>, and <code>$8A</code>; with <code>offset = 1</code>, also <code>$8B-$8C</code>. Preserves DBR and D. Includes <code>RTS</code>.

<code>%Draw()</code> draws a dynamic pose. Its arguments specify the graphics, palette, flip settings, and position to use.

'''Parameters'''

<pre>
%Draw(offset, sprite, lastPoseHashIndex, lastFlip, palette, xl, xh, yl, yh)
</pre>

* <code>offset</code>: 0 uses the supplied coordinates; 1 adds the signed 8-bit offsets <code>!XOffsetParam</code> (<code>$8A</code>) and <code>!YOffsetParam</code> (<code>$8B</code>).
* <code>sprite</code>: 1 restores the sprite index in X from <code>!SpriteIndex</code> before reading its palette and position; 0 skips this step.
* <code>lastPoseHashIndex</code>: variable identifying the entry where Dynamic Xtreme records the pose's graphics. If it contains <code>$FF</code>, nothing is drawn.
* <code>lastFlip</code>: variable or value specifying the flip settings for drawing.
* <code>palette</code>: palette variable or value; <code>$00</code> selects palette 8, <code>$02</code> selects 9, and so on up to <code>$0E</code> for F.
* <code>xl</code> and <code>xh</code>: variables or values for the low and high bytes of the X position.
* <code>yl</code> and <code>yh</code>: variables or values for the low and high bytes of the Y position.

'''Result'''

Draws the pose using the graphics identified by <code>lastPoseHashIndex</code> at the supplied X and Y position. You can pass a sprite's position variables or specify another position to draw from UberASM or other code.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
DrawPose:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMySprite_Frame0
%Draw(0, 1, "!NormalLastPoseHashIndex,x", "!NormalLastFlip,x", "!NormalPalette,x", "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

<code>!PoseIDMySprite_Frame0</code> is generated from the DrawInfo and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase by removing separators, as in <code>my_sprite</code> → <code>MySprite</code>. The ID must match the available dynamic graphics.

==== StandardSpriteDraw ====

'''Registers and temporary memory:''' follows [[#Draw|Draw]] and uses the same scratch memory, with <code>sprite = 1</code>. Enter with 16-bit A and 8-bit X/Y. Set X to the sprite index before calling it, because it reads the hash index before restoring <code>!SpriteIndex</code>. All three return in 8-bit mode. Includes <code>RTS</code>.

<code>%StandardSpriteDraw(offset, type)</code> draws a dynamic pose using the Dynamic Xtreme tables for the selected sprite type.

'''Parameters and inputs'''

* <code>offset</code>: 0 adds no offset; 1 uses the offsets in <code>$8A</code> and <code>$8B</code>.
* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code>, or <code>"Extended"</code>.
* 16-bit A: drawing pose ID.
* <code>!SpriteIndex</code>: sprite index.
* <code>!PropParam</code> and <code>!MaxTilePriorityParam</code>: properties and priority.
* Dynamic Xtreme palette, last flip, and hash index tables for the selected sprite type.

'''Result'''

The same result as <code>%Draw()</code>, using the standard tables. PIXI's <code>!DXDraw</code> and <code>!DXDrawWithOffset</code> routines use this macro.

For normal sprites, the PIXI routines prepare the coordinate aliases <code>!NormalXLow</code>, <code>!NormalXHigh</code>, <code>!NormalYLow</code>, and <code>!NormalYHigh</code>. If you expand the macro directly, these must also be defined, as in this example.

'''Example'''

<pre>
!NormalXLow = !SpriteXLow
!NormalXHigh = !SpriteXHigh
!NormalYLow = !SpriteYLow
!NormalYHigh = !SpriteYHigh

DrawPose:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMySprite_Frame0
%StandardSpriteDraw(0, "Normal")
</pre>

<code>!PoseIDMySprite_Frame0</code> is generated from the DrawInfo and written to <code>DXDefines.asm</code>. Its name uses PascalCase, with separators removed: <code>my_sprite</code> becomes <code>MySprite</code>.

==== DrawStatic ====

'''Registers and temporary memory:''' enter with 16-bit A and 8-bit X/Y. A and Y may change; X is preserved, but all three return in 8-bit mode. May overwrite <code>$00-$0F</code>, <code>$45-$4F</code>, and <code>$8A</code>; with <code>offset = 1</code>, also <code>$8B-$8C</code>. In this macro, <code>sprite</code> does not restore X from <code>!SpriteIndex</code>. Preserves DBR and D. Includes <code>RTS</code>.

<code>%DrawStatic()</code> draws a static pose declared with <code>.IsStatic</code> in the DrawInfo. Its graphics must already be loaded at the VRAM locations specified by its tiles.

'''Parameters'''

<pre>
%DrawStatic(offset, sprite, lastFlip, palette, xl, xh, yl, yh)
</pre>

* <code>offset</code>: 0 adds no offset; 1 uses the signed offsets <code>!XOffsetParam</code> (<code>$8A</code>) and <code>!YOffsetParam</code> (<code>$8B</code>).
* <code>sprite</code>: retained in the signature, but unused by the current implementation.
* <code>lastFlip</code>: flip variable or value; <code>#$00</code> draws without flipping.
* <code>palette</code>: palette variable or value; <code>#$00</code> selects palette 8, <code>#$02</code> selects 9, and so on up to <code>#$0E</code> for F.
* <code>xl</code> and <code>xh</code>: variables or values for the low and high bytes of the X position.
* <code>yl</code> and <code>yh</code>: variables or values for the low and high bytes of the Y position.

'''Additional inputs'''

* 16-bit A: static drawing pose ID.
* <code>!PropParam</code> (<code>$52</code>) and <code>!MaxTilePriorityParam</code> (<code>$0A</code>): properties and priority.
* <code>!Tile</code> (<code>$05</code>): tile number, when all tiles in the pose use the default value of 0. If the DrawInfo specifies other values, those tile numbers are used directly.

'''Result'''

Draws the pose without looking up the dynamic graphics cache. Requires neither <code>!LastPoseHashIndex</code> nor a prior call to <code>!Upload</code>.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
DrawPose:
LDA #$80
STA !Tile
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMyStaticSprite_Frame0
%DrawStatic(0, 1, #$00, #$04, "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

The example uses tile <code>$80</code> if the pose is configured to read it from <code>!Tile</code>, with no flipping and palette A. <code>!PoseIDMyStaticSprite_Frame0</code> is generated from the DrawInfo and written to <code>DXDefines.asm</code>. Its name uses PascalCase: separators are removed and each word starts with a capital letter, so <code>my_static_sprite</code> becomes <code>MyStaticSprite</code>.

=== Paletas ===

These macros let you choose a sprite's palette, upload its colors, and change them during gameplay.

==== LoadPaletteIDAndAddress ====

'''Registers and temporary memory:''' enter with 8-bit A; the macro sets the register sizes it needs to calculate addresses. Modifies A and X. Y is not used, but switches to 8-bit mode and loses its high byte if it was previously 16-bit. All three return in 8-bit mode. Writes <code>$00-$04</code> and reads <code>$0E-$0F</code>. Preserves DBR and D; carry does not report success. Execution continues after the macro.

<code>%LoadPaletteIDAndAddress()</code> retrieves a palette's ID and the ROM address of its colors. It selects a palette from the DynamicInfo: 0 for the first, 1 for the second, and so on. It does not upload colors; it provides these values for later use.

'''Inputs'''

* 8-bit A: palette index within the DynamicInfo.
* <code>$0E-$0F</code>: store your DynamicInfo's 16-bit <code>!MySpritePaletteTableOffset</code> define here, as shown in the example.

'''Result'''

* <code>$00-$01</code>: palette ID.
* <code>$02-$04</code>: ROM address of its colors in BGR555 format.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
REP #$20
LDA #!MySpritePaletteTableOffset
STA $0E
SEP #$20

LDA #$01 ; Second palette in the DynamicInfo
%LoadPaletteIDAndAddress()
; $00-$01 holds its ID; $02-$04 holds its ROM address.
</pre>

In PIXI, you can also use <code>%DXLoadPaletteIDAndAddress()</code>, with the same inputs and results. This variant calls a shared routine, then continues with the next instruction.

<code>!MySpritePaletteTableOffset</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names are normalized by removing spaces, underscores, and hyphens, then capitalizing the first letter of each word: <code>my_sprite</code> becomes <code>MySprite</code>.

==== PaletteAssignment (general macro) ====

'''Registers and temporary memory:''' enter with 8-bit X/Y and, when <code>PalettesChange</code> is enabled, 16-bit A. When it is disabled, enter with 8-bit A; the table offset is not used. A and Y may change; with <code>sprite = 1</code>, X is restored from <code>!SpriteIndex</code> when needed internally; with <code>sprite = 0</code>, X is not preserved. All three return in 8-bit mode. May overwrite <code>$00-$0F</code>, <code>$D5</code>, and effect temporary memory when applicable. Preserves DBR and D. Ends with <code>RTL</code>.

<code>%PaletteAssignment()</code> assigns and uploads a palette like <code>!PaletteAssignment</code>, but lets you specify the variables holding its options and state. Use it for an additional sprite palette or for code with its own variables.

If the palette is already assigned, it keeps its use timer at 2 to protect it from replacement while in use. If option bit <code>$80</code> is set, it also applies the appropriate global effect.

'''Parameters'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteAssignment(sprite, palette, paletteAssignment, paletteOption, paletteVersion, paletteLastVersion, manualIDGroup, manualID)
</pre>

* <code>sprite</code>: 1 uses <code>!SpriteIndex</code> to access sprite tables; 0 lets you use variables independent of the sprite index.
* <code>palette</code>: variable receiving the assigned palette. Initialize it to <code>$FF</code>. Values <code>$00</code>, <code>$02</code>, ..., <code>$0E</code> correspond to palettes 8–F.
* <code>paletteAssignment</code>: variable or value in <code>--AA----</code> format. <code>$00</code> lets Dynamic Xtreme choose the destination and upload the colors; <code>$10</code> uploads the colors to your chosen destination; <code>$20</code> uses that destination with the colors already loaded in the level.
* <code>paletteOption</code>: variable or value in <code>EPPP----</code> format. E = 1 enables the global effect; E = 0 excludes this palette from it. In manual mode, PPP selects palette 8 (<code>000</code>) through F (<code>111</code>). In automatic mode, <code>000</code> allows all palettes, nonzero <code>0XX</code> allows 8–B, and <code>1XX</code> allows C–F. These options do not use the low four bits.
* <code>paletteVersion</code>: variable or value selecting a palette from the DynamicInfo list: 0 for the first, 1 for the second, and so on. Sprite routines use <code>!Version,x</code> for this.
* <code>paletteLastVersion</code>: variable holding the last processed version. Initialize it to <code>$FF</code>.
* <code>manualIDGroup</code> and <code>manualID</code>: together, these identify the palette in manual modes. The first selects the group: <code>#$FE</code> for normal, <code>#$FC</code> for cluster, and <code>#$FD</code> for extended sprites. The second identifies the sprite type; normal sprites use <code>!CustomSpriteNumber,x</code>, as shown in the example.

You can also define your own groups: for example, <code>manualIDGroup = #$FB</code> for the player and <code>#$FA</code> for another type of entity. These are examples, not predefined Dynamic Xtreme values. Choose values not already used by another group, and use <code>manualID</code> to distinguish resources within each group. Groups <code>$FE</code>, <code>$FD</code>, and <code>$FC</code> are already used by the normal, extended, and cluster sprite routines, respectively.

'''Additional input'''

* 16-bit A: <code>!MySpritePaletteTableOffset</code> for the DynamicInfo containing the palettes.
* With <code>sprite = 1</code>, <code>!SpriteIndex</code> must contain the sprite index.

'''Result'''

* Carry set: a palette is available for drawing. Carry clear: none is available yet.
* Stores the palette number in <code>palette</code> and updates <code>paletteLastVersion</code> when processing the version.
* A, X, and Y return in 8-bit mode.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
%PaletteAssignment(1, "!NormalPalette,x", "!NormalPaletteAssignment,x", "!NormalPaletteOption,x", "!NormalVersion,x", "!NormalLastVersion,x", #$FE, "!CustomSpriteNumber,x")
</pre>

The example uses normal sprite variables. <code>!MySpritePaletteTableOffset</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase by removing separators: <code>my_sprite</code> becomes <code>MySprite</code>.

Call the example routine with <code>JSL PaletteManagement</code>. The macro includes the <code>RTL</code> that ends the routine, so do not place more code after it.

==== PaletteAssignmentNoUpload (general macro) ====

'''Registers and temporary memory:''' follows [[#PaletteAssignment_(general_macro)|PaletteAssignment (general macro)]]. In addition to carry, returns Y as described below; do not keep another value in Y if you need it afterward. Outputs in <code>$00-$04</code> are valid only when a palette was read from the DynamicInfo. Ends with <code>RTL</code>.

<code>%PaletteAssignmentNoUpload()</code> selects a palette like <code>%PaletteAssignment()</code>, but leaves the color upload pending. This lets you apply a local effect and combine it with the global effect afterward.

'''Parameters and inputs'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteAssignmentNoUpload(sprite, palette, paletteAssignment, paletteOption, paletteVersion, paletteLastVersion, manualIDGroup, manualID)
</pre>

Takes the same parameters as <code>%PaletteAssignment()</code>. A receives the 16-bit table offset. Initialize <code>palette</code> and <code>paletteLastVersion</code> to <code>$FF</code>.

<code>paletteVersion</code> selects colors from the DynamicInfo list: 0 for the first palette, 1 for the second, and so on. <code>paletteAssignment</code> selects the mode: <code>$00</code> automatic, <code>$10</code> manual, and <code>$20</code> manual without uploading colors. <code>paletteOption</code> uses <code>EPPP----</code>: E enables the global effect, and PPP selects palette 8–F in manual mode. In automatic mode, <code>000</code> allows all palettes, nonzero <code>0XX</code> allows 8–B, and <code>1XX</code> allows C–F. To apply a local effect to the DynamicInfo colors afterward, use automatic assignment or manual assignment with upload.

'''Result'''

* Carry set: a palette is assigned. Carry clear: assignment failed.
* <code>palette</code>: assigned palette number, in steps of two from <code>$00</code> to <code>$0E</code>.
* <code>paletteLastVersion</code>: last processed version.
* <code>$00-$01</code>: ID of the palette selected from the DynamicInfo.
* <code>$02-$04</code>: ROM address of its colors.
* Y = 1 means the palette was just assigned and its effect must be calculated. Y = 0 means a new assignment does not require recalculation.
* A, X, and Y return in 8-bit mode.

Use the values in <code>$00-$04</code> only when the call read a palette from the DynamicInfo. If you use an existing level palette without uploading it, disable palette changes, or call from a game mode where processing is skipped, these addresses may contain values left by other code.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
AssignPaletteForEffect:
REP #$20
LDA #!MySpritePaletteTableOffset
%PaletteAssignmentNoUpload(1, "!NormalPalette,x", "!NormalPaletteAssignment,x", "!NormalPaletteOption,x", "!NormalVersion,x", "!NormalLastVersion,x", #$FE, "!CustomSpriteNumber,x")
</pre>

After calling <code>AssignPaletteForEffect</code> with <code>JSL</code>, check carry and apply the effect using the returned values. Keep Y and <code>$02-$04</code> intact for the concatenation call.

The macro ends its routine with <code>RTL</code>. Put the effect code after the <code>JSL AssignPaletteForEffect</code> call, not after the macro inside that routine.

<code>!MySpritePaletteTableOffset</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Its name uses PascalCase, with separators removed: <code>my_sprite</code> becomes <code>MySprite</code>.

==== StandardSpritePaletteAssignment ====

'''Registers and temporary memory:''' follows [[#PaletteAssignment_(general_macro)|PaletteAssignment (general macro)]], with <code>sprite = 1</code>. Enter with X set to read the sprite's tables and <code>!SpriteIndex</code> identifying the same sprite. Restores X from that index when needed internally; A and Y may change. Includes <code>RTL</code>.

<code>%StandardSpritePaletteAssignment()</code> uses the palette variables for the specified sprite type. PIXI's palette assignment routines use this macro.

'''Parameters and inputs'''

<pre>
%StandardSpritePaletteAssignment(type, manualIDGroup, manualID)
</pre>

* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code>, or <code>"Extended"</code>.
* <code>manualIDGroup</code>: <code>#$FE</code> for normal, <code>#$FC</code> for cluster, or <code>#$FD</code> for extended sprites.
* You can also choose your own group, such as <code>#$FB</code> for the player or <code>#$FA</code> for another type of entity, provided no other group in your project uses those values.
* <code>manualID</code>: variable or value identifying the sprite type in manual modes.
* 16-bit A: <code>!MySpritePaletteTableOffset</code> for the DynamicInfo containing the palettes.
* <code>!SpriteIndex</code>: sprite index.
* Dynamic Xtreme palette, option, version, and last-version variables for the selected type, prepared as described for <code>!PaletteAssignment</code>.

'''Result'''

The same result as <code>!PaletteAssignment</code>: stores the assigned palette in the sprite table and returns carry set when it can be used for drawing.

The macro includes <code>RTL</code>. Call the example routine with <code>JSL PaletteManagement</code> and do not place more code after the macro.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
%StandardSpritePaletteAssignment("Normal", #$FE, "!CustomSpriteNumber,x")
</pre>

<code>!MySpritePaletteTableOffset</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase: <code>my_sprite</code> becomes <code>MySprite</code> when separators are removed.

==== StandardSpritePaletteAssignmentNoUpload ====

'''Registers and temporary memory:''' follows [[#PaletteAssignmentNoUpload_(general_macro)|PaletteAssignmentNoUpload (general macro)]], with <code>sprite = 1</code>. X and <code>!SpriteIndex</code> must identify the same sprite on entry. Keep the returned Y and <code>$02-$04</code> intact if you will concatenate an effect. Includes <code>RTL</code>.

<code>%StandardSpritePaletteAssignmentNoUpload()</code> uses the selected sprite type's variables to assign a palette, leaving the color upload pending.

'''Parameters and inputs'''

<pre>
%StandardSpritePaletteAssignmentNoUpload(type, manualIDGroup, manualID)
</pre>

Takes the same parameters and inputs as <code>%StandardSpritePaletteAssignment()</code>. A must hold the 16-bit palette table offset.

'''Result'''

The same result as <code>!PaletteAssignmentNoUpload</code>: stores the assigned palette and returns carry, Y, the ID in <code>$00-$01</code>, and the address in <code>$02-$04</code>, under the conditions described in that entry.

The macro includes <code>RTL</code>. Call the example routine with <code>JSL AssignPaletteForEffect</code>. Put the effect code after that call.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
AssignPaletteForEffect:
REP #$20
LDA #!MySpritePaletteTableOffset
%StandardSpritePaletteAssignmentNoUpload("Normal", #$FE, "!CustomSpriteNumber,x")
</pre>

<code>!MySpritePaletteTableOffset</code> is generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Its name is normalized to PascalCase by removing separators: <code>my_sprite</code> becomes <code>MySprite</code>.

==== ReplacePalette (general macro) ====

'''Registers and temporary memory:''' enter with 8-bit A, X, and Y, and the source pointer in <code>$02-$04</code>. A and Y may change; with <code>sprite = 1</code>, X is restored from <code>!SpriteIndex</code>; with <code>sprite = 0</code>, X is not preserved. All three return in 8-bit mode. May overwrite <code>$00-$01</code> and effect temporary memory when applicable. Preserves DBR and D. Ends with <code>RTL</code>.

<code>%ReplacePalette()</code> replaces the colors of a palette already in use. It works like <code>!ReplacePalette</code>, but lets you choose which variables to read. Other sprites or code sharing that palette will also use the new colors.

It is commonly used after assignment without upload, such as <code>%PaletteAssignmentNoUpload()</code>. First obtain the assigned palette, then put the address of the replacement colors in <code>$02-$04</code>.

'''Parameters and inputs'''

<pre>
%ReplacePalette(sprite, paletteOption, palette)
</pre>

* <code>sprite</code>: 1 retrieves the sprite index from <code>!SpriteIndex</code>; 0 uses variables independent of that index.
* <code>paletteOption</code>: palette option variable or value. Bit <code>$80</code> controls whether the global effect is applied.
* <code>palette</code>: destination palette variable or value, in steps of two from <code>$00</code> to <code>$0E</code>.
* <code>$02-$04</code>: ROM address of the new BGR555 colors.
* A in 8-bit mode.

'''Result'''

Changes the colors without changing the assignment ID. Returns carry set when colors are available for drawing, including the previous colors if the change could not be completed yet. Returns carry clear if no result is available.

Call it when the colors need to change. Calling it every frame makes the system prepare the palette and its effects again each time.

Call the example routine with <code>JSL ReplaceSpritePalette</code>. The macro includes the <code>RTL</code> that ends the routine.

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
ReplaceSpritePalette:
LDA.b #!PaletteMyAlternatePalette
STA $02
LDA.b #!PaletteMyAlternatePalette>>8
STA $03
LDA.b #!PaletteMyAlternatePalette>>16
STA $04
%ReplacePalette(1, "!NormalPaletteOption,x", "!NormalPalette,x")
</pre>

<code>!PaletteMyAlternatePalette</code> is the address of a palette inserted from the DynamicInfo's resources and written to <code>DXDefines.asm</code>. Its name is normalized by removing separators and capitalizing each word: <code>my_alternate_palette</code> becomes <code>MyAlternatePalette</code>.

==== Uploading colors with TransferPalette ====

These macros upload colors to a palette you choose, without automatic assignment. Use them to change a background palette, a palette set aside for a sprite, or colors prepared in RAM.

They also update the game's palette copies and prepare the effect state, unlike the PPU transfer macros. You do not need to copy the buffers or invalidate their effect flags manually.

'''Common parameters'''

* <code>CGRAMOffset</code>: first color to change, from <code>$00</code> to <code>$FF</code>. This is an 8-bit operand: <code>#$91</code> starts at color 1 of palette 9; <code>$00</code> uses the number stored in that scratch byte.
* <code>Length</code>: number of bytes to copy. This is an assembly-time value, '''without <code>#</code>''': <code>$001E</code> copies 15 colors. It must be positive and even, and the upload must not extend beyond the last CGRAM color.
* <code>GlobalEffect</code>: use <code>0</code> to upload without the global effect, or <code>1</code> to apply the global effect. This is a fixed option in the call, not a RAM variable.

'''What GlobalEffect does'''

{| class="wikitable"
! Value !! Behavior
|-
| <code>0</code> || Schedules a transfer of the colors without an effect and updates the SMW and Dynamic Xtreme buffers. If effects are enabled, excludes the modified palettes from the global effect.
|-
| <code>1</code> || Stores the original colors so the system can apply the global effect before uploading them. Marks the modified palettes to receive the effect and clears their previous effect flags.
|}

With <code>GlobalEffect = 1</code>, no unaffected version is uploaded first: the upload waits for the effect result. This also prepares a palette for global effects when the current global effect ID is still 0. If palette effects are disabled in the installation, the call uses a direct upload.

These options affect every 16-color palette touched by the upload, not just the copied colors. When uploading with the global effect enabled, supply all visible colors of each affected palette: for example, the 15 colors of a sprite palette, starting at color 1. Do not rely on a partial upload to preserve original colors you have not prepared yet.

'''Common inputs and results'''

* Enter with 8-bit A, X, and Y. D must be <code>$0000</code> in LoROM or <code>$3000</code> in the usual SA-1 Pack context. DBR must allow access to SMW's palette buffer: <code>$0703</code> in LoROM or its <code>$6703</code> mirror in SA-1. The usual banks with RAM mirrors, such as <code>$00-$3F</code> and <code>$80-$BF</code>, allow these accesses. If you pass tables using 16-bit addresses, DBR must also allow access to them.
* Carry set: the direct transfer was accepted, or the original colors were prepared for the global effect. In the latter case, this does not mean the result has already been uploaded to CGRAM.
* Carry clear: the direct transfer was rejected because of the frame's data limit. You can retry later; the buffers and effect flags for this upload remain unchanged.
* A and X may change on both success and failure. Y may change when colors are copied; do not use it to preserve another value across calls. All three return in 8-bit mode in either case. DBR and D are preserved.
* Calls may modify <code>$68-$6D</code> when effects are enabled. The <code>FromAddress</code>, <code>FromTable</code>, and <code>Resource</code> variants, including <code>ResourceWithLength</code>, also use <code>$65-$67</code>. Do not store the source pointer or destination color in scratch memory that the call overwrites before it finishes using those values.
* Includes neither <code>RTS</code> nor <code>RTL</code>: execution continues after the macro.

If the source is in RAM, you must keep its contents unchanged until the scheduled transfer takes place. The source data must not cross a bank boundary. For <code>CGRAMOffset</code>, use an immediate value or a variable that remains valid after the macro changes X and Y; avoid operands indexed by those registers.

Call these macros when the colors need to change, rather than every frame while the palette stays the same. If you use a sprite palette at a fixed destination, restrict it so automatic assignment does not use it.

==== TransferPaletteFromAddress ====

<code>%TransferPaletteFromAddress()</code> uploads colors from an address known at assembly time. This can be a label in your code or a define containing the resource's full address.

'''Parameters'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromAddress(Address, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Address</code>: full source address, without <code>#</code>.
* Other parameters and carry work as described in [[#Uploading_colors_with_TransferPalette|Uploading colors with TransferPalette]].

'''Example'''

<pre>
; Palette 9, colors 1-F, with the global effect.
%TransferPaletteFromAddress(!PaletteMyPalette, #$91, $001E, 1)
</pre>

<code>!PaletteMyPalette</code> is generated when installing a palette declared in a DynamicInfo's <code>Palettes</code> section and written to <code>DXDefines.asm</code>. Names use PascalCase: spaces, underscores, and hyphens are removed, and each word starts with a capital letter. For example, <code>my_palette</code> becomes <code>MyPalette</code>.

==== TransferPaletteFromPointer ====

<code>%TransferPaletteFromPointer()</code> uses a source address already stored in three consecutive scratch bytes. This is useful when your code selects a palette during gameplay.

'''Parameters'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromPointer(Pointer, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Pointer</code>: address of the first scratch byte, without <code>#</code>. The three bytes must hold the source address in low-byte, high-byte, bank order. For example, <code>$02</code> uses <code>$02-$04</code>.
* Other parameters and carry work as described in [[#Uploading_colors_with_TransferPalette|Uploading colors with TransferPalette]].

'''Example'''

<pre>
; Put the palette address in $02-$04.
REP #$20
LDA.w #!PaletteMyPalette
STA $02
SEP #$20
LDA.b #!PaletteMyPalette>>16
STA $04

; Palette 9, colors 1-F, without the global effect.
%TransferPaletteFromPointer($02, #$91, $001E, 0)
</pre>

<code>!PaletteMyPalette</code> is generated from a DynamicInfo palette and written to <code>DXDefines.asm</code>. Its name is normalized to PascalCase by removing separators: <code>my_palette</code> becomes <code>MyPalette</code>.

==== TransferPaletteFromTable ====

<code>%TransferPaletteFromTable()</code> accepts the source's two address bytes and bank byte separately. These can come from tables, variables, or immediate values. The macro combines them in <code>$65-$67</code>.

'''Parameters'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromTable(TableAddr, TableBNK, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>TableAddr</code>: operand read with 16-bit A to obtain the two address bytes.
* <code>TableBNK</code>: operand read with 8-bit A to obtain the bank.
* Other parameters and carry work as described in [[#Uploading_colors_with_TransferPalette|Uploading colors with TransferPalette]].

'''Example'''

<pre>
; $02-$03 holds the address; $04 holds the bank.
%TransferPaletteFromTable("$02", "$04", #$91, $001E, 1)
</pre>

Unlike <code>FromPointer</code>, the address and bank operands do not need to occupy consecutive bytes. If you read them from tables in your code, the data bank must allow access to those tables.

==== TransferPaletteResource ====

<code>%TransferPaletteResource()</code> uploads an entire palette registered in the DynamicInfo. You do not need to specify its address or byte count.

'''Parameters'''

<pre>
%TransferPaletteResource(Name, CGRAMOffset, GlobalEffect)
</pre>

* <code>Name</code>: normalized palette name, without the <code>!Palette</code> prefix or file extension. The macro uses <code>!Palette<Name></code> and <code>!Palette<Name>Size</code>.
* Other parameters and carry work as described in [[#Uploading_colors_with_TransferPalette|Uploading colors with TransferPalette]].

'''Example'''

<pre>
; MyPalette contains 15 colors.
%TransferPaletteResource(MyPalette, #$91, 1)
BCS .Accepted
; Direct upload rejected: retry later.
RTL
.Accepted
; Continue with the rest of the code.
</pre>

The example continues at <code>.Accepted</code> if the direct upload was accepted or the colors were prepared for the global effect. The <code>RTL</code> belongs to the example, not the macro.

<code>MyPalette</code> corresponds to <code>!PaletteMyPalette</code> and <code>!PaletteMyPaletteSize</code>, generated in <code>DXDefines.asm</code> from the DynamicInfo's <code>Palettes</code> section. Names use PascalCase, with spaces, underscores, and hyphens removed: <code>my_palette</code> becomes <code>MyPalette</code>. This call does not use <code>!Resource...</code> defines from the <code>Resources</code> section or converted RGB/HSL palettes from a <code>*.paleffect</code> file.

==== TransferPaletteResourceWithLength ====

<code>%TransferPaletteResourceWithLength()</code> uses a registered palette's address, but copies only the number of bytes you specify.

'''Parameters'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteResourceWithLength(Name, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Name</code>: normalized palette name, as in <code>%TransferPaletteResource()</code>.
* <code>Length</code>: number of bytes to copy, without <code>#</code>. Must not exceed the resource size.
* Other parameters and carry work as described in [[#Uploading_colors_with_TransferPalette|Uploading colors with TransferPalette]].

'''Example'''

<pre>
; Copy 4 colors to the start of palette 9, without the global effect.
%TransferPaletteResourceWithLength(MyPalette, #$90, $0008, 0)
</pre>

<code>MyPalette</code> uses <code>!PaletteMyPalette</code>, generated from a DynamicInfo palette and written to <code>DXDefines.asm</code>. Its name is normalized to PascalCase by removing separators: <code>my_palette</code> becomes <code>MyPalette</code>.

<code>TransferPaletteCommon</code> and <code>TransferPaletteData</code> are internal components shared by these calls. To upload palettes from your code, use the variants above, which also prepare the effect state.

=== Palette effects ===

These macros change a palette's colors: tint it, adjust its brightness, transition between palettes, or apply an effect saved in a <code>*.paleffect</code> file.

For complete examples, see [[Dynamic_Xtreme_UberASM_guide#Applying_a_global_palette_effect|Applying a global palette effect]] in the UberASM guide, which covers a fixed effect, a cycle, and a transition. [[Dynamic_Xtreme_UberASM_guide#Changing_palettes_during_gameplay|Changing palettes during gameplay]] shows how to upload colors with <code>TransferPalette</code> and check whether the call was accepted.

RGB works with red, green, and blue. HSL works with hue, saturation, and lightness. Choose RGB or HSL macros according to the change you want. See [[Dynamic_Xtreme_files_and_formats#Effect_types|Effect types]] for the available effects.

'''Which call do you need?'''

{| class="wikitable"
! To… !! Use…
|-
| Tint a palette or change its hue, saturation, or lightness. || <code>Mix</code> / <code>MixAndMerge</code>.
|-
| Transition from one palette to another. || <code>PaletteTransition</code>.
|-
| Apply an effect already defined in a <code>*.paleffect</code> file. || <code>DoEffect</code> / <code>DoEffectAndMerge</code>.
|-
| Give a sprite its own effect while keeping the global effect. || <code>ConcatenateRGBPaletteEffectToGlobal</code> or its HSL variant, after assigning the palette without upload.
|}

To calculate an effect directly, first prepare the original colors with <code>SetRGBBase</code> or <code>SetHSLBase</code>, then apply the change. The examples use <code>Default</code> variants, which work with Dynamic Xtreme's palette copies so you do not need to specify memory addresses.

The <code>AndMerge</code> variants produce colors in the format the SNES needs to display them. Calculating them does not upload them automatically: palette handling or a CGRAM transfer completes the upload. When used after <code>PaletteAssignmentNoUpload</code>, the concatenation routines handle both color preparation and the upload.

Set A to 8-bit mode before calling the macros in these examples.

'''Effect registers and temporary memory'''

* Base preparation, mixing, transition, conversion, and <code>DoEffect</code> macros take 8-bit A, X, and Y. Their <code>Default</code> variants follow the same requirements. Concatenation macros take different inputs, described in their section.
* These macros prepare their arguments and call the patch routine internally. Execution then continues at the next instruction; they do not include a return that ends your routine.
* Treat A, X, and Y as temporary; they return in 8-bit mode. Carry does not report success or failure: the result is the colors written to the destination buffer. DBR and D are preserved under the [[#CPU_state_and_temporary_memory|CPU state]] rules.
* Depending on the operation, they may overwrite <code>$00-$0F</code>, <code>$45-$54</code>, <code>$6A</code>, <code>$8A-$8F</code>, and <code>$D5-$D7</code>. These locations hold pointers, lengths, channels, and ratios; do not store values there that must survive the call.
* Source and destination banks are read with 8-bit A; addresses, offsets, and color counts are read with 16-bit A during preparation. Channels and ratios are read with 8-bit A. The <code>DoEffect</code> ID is read with 16-bit A. Prepare memory operands at the corresponding size.
* If your operands are indexed, X and Y must identify their data on entry. Their values may change during the call. In the full variants, arguments must also avoid overlapping temporary values prepared before those arguments are read.

==== Preparing colors: SetRGBBase and SetHSLBase ====

Before changing colors, you need a working copy for the effect calculations. <code>%SetRGBBase()</code> prepares it for RGB effects; <code>%SetHSLBase()</code> prepares it for HSL. If the original colors have not changed, you can reuse this copy in later frames.

The <code>Default</code> variants only require the first color and the number of colors to prepare:

<pre>
%SetRGBBaseDefault(offset, length)
%SetHSLBaseDefault(offset, length)
</pre>

<code>offset</code> is the first color number, and <code>length</code> is the color count. For example, <code>#$0081</code> and <code>#$000F</code> select palette 8's 15 visible colors.

Use the full versions if you need to choose the addresses to read from and write to:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%SetRGBBase(src, srcbnk, dst, dstbnk, offset, length)
%SetHSLBase(src, srcbnk, dst, dstbnk, offset, length)
</pre>

<code>%SetRGBBaseDefault(offset, length)</code> and <code>%SetHSLBaseDefault(offset, length)</code> read from <code>DX_PPU_CGRAM_PaletteCopy</code> and write the result to <code>DX_PPU_CGRAM_BaseRGBPalette</code> or <code>DX_PPU_CGRAM_BaseHSLPalette</code>.

'''Example: preparing a sprite palette'''

<pre>
; Palette 8, excluding its first, transparent color.
%SetRGBBaseDefault(#$0081, #$000F)

; Use this variant instead to work in HSL:
; %SetHSLBaseDefault(#$0081, #$000F)
</pre>

<code>$81</code> is palette 8's second color: the palette starts at color <code>$80</code>, and the next 15 colors are processed.

==== Mixing colors: Mix and MixAndMerge ====

These macros move the original colors toward values you specify. For example, move red toward 31 and green and blue toward 0 to tint a palette red. Changing the ratios gradually makes the effect fade in.

The <code>v</code> parameters specify the target color values, from 0 to 31. The <code>r</code> parameters control how far to move toward them: 0 keeps the original, 127 applies the full change, and 64 applies roughly half. The examples write these as <code>#$00</code>, <code>#$7F</code>, and <code>#$40</code>.

For RGB, components 1, 2, and 3 are red, green, and blue. For HSL, they are hue, saturation, and lightness.

The end of the name identifies the components to change:

{| class="wikitable"
! RGB !! HSL !! Components changed
|-
| <code>R</code>, <code>G</code>, <code>B</code> || <code>H</code>, <code>S</code>, <code>L</code> || One.
|-
| <code>RG</code>, <code>RB</code>, <code>GB</code> || <code>HS</code>, <code>HL</code>, <code>SL</code> || Two.
|-
| <code>RGB</code> || <code>HSL</code> || All three.
|}

Each combination is available as <code>Mix...</code>, <code>MixAndMerge...</code>, and <code>MixAndMerge...Default</code>. For example: <code>%MixR()</code>, <code>%MixAndMergeR()</code>, and <code>%MixAndMergeRDefault()</code>.

Supply the selected components' ratios first, then their target values, in the order given by the name. Source and destination addresses, first color, and color count follow. <code>Default</code> variants omit the addresses.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%MixRGB(r1, r2, r3, v1, v2, v3, src, srcbnk, dst, dstbnk, offset, length)
%MixAndMergeRG(r1, r2, v1, v2, src, srcbnk, dst, dstbnk, offset, length)
%MixAndMergeLDefault(r3, v3, offset, length)
</pre>

'''RGB example: tinting a palette red'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Prepare palette 8's original colors.
%SetRGBBaseDefault(#$0081, #$000F)

; Move all three components roughly halfway toward pure red.
%MixAndMergeRGBDefault(#$40, #$40, #$40, #$1F, #$00, #$00, #$0081, #$000F)

</pre>

The first three <code>#$40</code> values set the strength of the change for red, green, and blue. The next three, <code>#$1F, #$00, #$00</code>, specify pure red as the target. The last two select palette 8's 15 colors.

'''HSL example: lightening a palette'''

<pre>
%SetHSLBaseDefault(#$0081, #$000F)
%MixAndMergeLDefault(#$40, #$1F, #$0081, #$000F)
</pre>

Only lightness changes here: <code>#$40</code> applies roughly half the change, and <code>#$1F</code> is maximum lightness. This example is independent of the previous one.

==== Transitioning between palettes: PaletteTransition ====

These macros move each original color toward the corresponding color in another palette. Unlike <code>Mix</code>, each color has its own target. For example, they can transition a sprite from its normal colors to a damage palette.

The variants are <code>PaletteTransitionRGB</code>, <code>PaletteTransitionHSL</code>, <code>PaletteTransitionRGBAndMerge</code>, and <code>PaletteTransitionHSLAndMerge</code>. Both <code>AndMerge</code> variants also have a <code>Default</code> version.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteTransitionRGB(r1, r2, r3, src, srcbnk, targetpal, targetpalbnk, dst, dstbnk, offset, length)
%PaletteTransitionHSLAndMerge(r1, r2, r3, src, srcbnk, targetpal, targetpalbnk, dst, dstbnk, offset, length)
%PaletteTransitionRGBAndMergeDefault(r1, r2, r3, targetpal, targetpalbnk, offset, length)
</pre>

<code>targetpal</code> and <code>targetpalbnk</code> specify the target palette's address and bank. Prepare it with 3 bytes per color, in RGB or HSL according to the macro. The ratios control how far each component moves toward its target.

'''Example: calculating an intermediate transition step'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; This example uses the palette copy's first 15 colors.
%SetRGBBaseDefault(#$0000, #$000F)
%PaletteTransitionRGBAndMergeDefault(#$40, #$40, #$40, #!PaletteMyTargetRGB, #!PaletteMyTargetRGB>>16, #$0000, #$000F)
</pre>

The example assumes <code>!PaletteMyTargetRGB</code> is an RGB target palette generated when installing a transition <code>*.paleffect</code>. Its address is written to <code>DXDefines.asm</code>. Names are normalized by removing spaces, hyphens, and underscores and capitalizing each word: <code>my_target</code> becomes <code>MyTarget</code>. For HSL, use the HSL-converted palette and the corresponding macro.

==== Applying an effect from a file: DoEffect ====

<code>%DoEffect()</code> applies an effect from a <code>*.paleffect</code> file by ID. The file already defines the effect type, color values, and ratios, so you do not need to supply them individually.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%DoEffect(effect, src, srcbnk, dst, dstbnk, offset, length)
%DoEffectAndMerge(effect, src, srcbnk, dst, dstbnk, offset, length)
%DoEffectAndMergeDefaultRGB(effect, offset, length)
%DoEffectAndMergeDefaultHSL(effect, offset, length)
</pre>

* <code>effect</code>: effect ID, such as <code>#!PaletteEffectIDMyEffect0</code>.
* The source must contain separate RGB or HSL components, depending on the selected effect.
* <code>DoEffect</code> writes 3 bytes per color so you can apply further changes.
* <code>DoEffectAndMerge</code> writes colors in SNES format. The <code>DefaultRGB</code> and <code>DefaultHSL</code> variants select the corresponding base and write to <code>DX_PPU_CGRAM_PaletteWriteMirror</code>.

'''Example: applying an RGB effect to palette 8'''

<pre>
%SetRGBBaseDefault(#$0081, #$000F)
%DoEffectAndMergeDefaultRGB(#!PaletteEffectIDMyEffect0, #$81, #$000F)
</pre>

<code>!PaletteEffectIDMyEffect0</code> is generated from a <code>*.paleffect</code> file and written to <code>DXDefines.asm</code>. Its name is normalized to PascalCase by removing separators: <code>my_effect</code> becomes <code>MyEffect</code>. The final number identifies the effect within the file. For an HSL effect, prepare the HSL base and use <code>%DoEffectAndMergeDefaultHSL()</code>.

==== Converting between RGB and HSL ====

<code>%RGBToHSL()</code> converts RGB colors to HSL; <code>%HSLToRGB()</code> converts them back. Both read and write 3 bytes per color. Use them when you want to continue modifying a palette with an effect that uses the other color space.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%RGBToHSL(src, srcbnk, dst, dstbnk, offset, length)
%HSLToRGB(src, srcbnk, dst, dstbnk, offset, length)
</pre>

'''Example: converting the RGB base to HSL'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%RGBToHSL(#DX_PPU_CGRAM_BaseRGBPalette, #DX_PPU_CGRAM_BaseRGBPalette>>16, #DX_PPU_CGRAM_BaseHSLPalette, #DX_PPU_CGRAM_BaseHSLPalette>>16, #$0081, #$000F)
</pre>

The example reads palette 8's 15 colors from the RGB base and writes their equivalents to the HSL base. Prepare the RGB base before calling the conversion.

==== Combining a local effect with the global effect ====

'''Registers and temporary memory:''' these two macros take 16-bit A, 8-bit X holding the palette value, and 8-bit Y holding the result of assignment without upload. All three return in 8-bit mode. With <code>sprite = 1</code>, X is restored from <code>!SpriteIndex</code>; with <code>sprite = 0</code>, X is not preserved. A and Y may change. Uses effect temporary memory and <code>$F0-$F3</code>. Preserves DBR and D. Unlike the other effect macros, these include <code>RTL</code> and report availability through carry, including when reusing a previous result.

<code>%ConcatenateRGBPaletteEffectToGlobal()</code> and <code>%ConcatenateHSLPaletteEffectToGlobal()</code> apply a local effect to a palette that must also receive the global effect. The sprite calls of the same name use these macros, but the macros let you choose your palette variables.

They are commonly used after <code>%PaletteAssignmentNoUpload()</code> or its sprite variant: assign the palette without uploading colors, then apply the effects. Keep the assignment's returned values intact for this second call.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%ConcatenateRGBPaletteEffectToGlobal(sprite, paletteOption, palette)
%ConcatenateHSLPaletteEffectToGlobal(sprite, paletteOption, palette)
</pre>

* <code>sprite</code>: 1 restores the sprite index from <code>!SpriteIndex</code>; 0 lets you use your own variables.
* <code>paletteOption</code>: palette option variable or value; set bit <code>$80</code> to include the global effect.
* <code>palette</code>: variable holding the assigned palette, in steps of two from <code>$00</code> to <code>$0E</code>.
* 16-bit A: local RGB or HSL effect ID, according to the macro.
* 8-bit X: copy of the assigned palette value.
* 8-bit Y: keep the value returned by assignment without upload.
* <code>$02-$04</code>: original color address prepared by that assignment.

Returns carry set if drawing can use the requested effect, or the previous effect while the new one is being prepared. Returns carry clear if no result is available yet. Both macros end the routine with <code>RTL</code>.

'''Example: completing assignment without upload'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Call this routine with JSL after assigning the palette without upload.
; Keep Y and $02-$04 from that call intact.
ApplyLocalEffect:
LDA !NormalPalette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyEffect0
%ConcatenateRGBPaletteEffectToGlobal(1, "!NormalPaletteOption,x", "!NormalPalette,x")
</pre>

<code>!PaletteEffectIDMyEffect0</code> is generated from a <code>*.paleffect</code> file and written to <code>DXDefines.asm</code>. Its name is normalized to PascalCase by removing separators: <code>my_effect</code> becomes <code>MyEffect</code>. Use the HSL macro for an HSL effect. If you use Y to read an effect table, save it with <code>PHY</code> and restore it with <code>PLY</code> before concatenating.

==== Choosing addresses and combining several effects ====

The examples' <code>Default</code> variants choose the addresses for you. Use the full versions to store results elsewhere or apply several effects in sequence. Their address parameters are:

* <code>src</code>: where to read the original colors; <code>srcbnk</code>: their bank.
* <code>dst</code>: where to write the result; <code>dstbnk</code>: its bank. The destination must be RAM available to your code.
* <code>offset</code>: first color to process, counting from 0.
* <code>length</code>: number of colors to process.

For a fixed address, use <code>#Nombre</code> for the address and <code>#Nombre>>16</code> for its bank, as in the RGB-to-HSL example. You can also pass variables containing these values.

The required space depends on the operation:

{| class="wikitable"
! Operation !! Reads !! Writes
|-
| <code>SetRGBBase</code> / <code>SetHSLBase</code> || Standard palette: 2 bytes per color. || Separate components: 3 bytes per color.
|-
| <code>Mix</code>, <code>PaletteTransition</code>, <code>DoEffect</code> without <code>AndMerge</code> || Separate components: 3 bytes per color. || Separate components: 3 bytes per color.
|-
| <code>AndMerge</code> variants || Separate components: 3 bytes per color. || Standard palette: 2 bytes per color.
|-
| <code>RGBToHSL</code> / <code>HSLToRGB</code> || Separate components: 3 bytes per color. || Separate components: 3 bytes per color.
|}

For example, to apply two effects in sequence, the first must write separate components, without <code>AndMerge</code>. The second reads that result and uses <code>AndMerge</code> to prepare the palette for upload. If one effect uses RGB and the other HSL, convert the colors between steps.

Depending on the operation, the macros use temporary memory including <code>$45-$50</code>, <code>$51-$53</code>, <code>$6A</code>, <code>$8A</code>, <code>$8C</code>, <code>$8E</code>, <code>$0E-$0F</code>, and <code>$D5-$D7</code>. Do not store values there that you need to keep after the call.

=== PPU ===

These macros upload graphics to VRAM and colors to CGRAM. The SNES stores graphics in VRAM and their palettes in CGRAM.

A call schedules a transfer for the next NMI, when the game can update those memories. It does not copy the data immediately. The source data must remain available until the transfer takes place.

'''Which call to use'''

{| class="wikitable"
! To… !! VRAM !! CGRAM
|-
| Supply the source address and bank separately. || <code>TransferToVRAM</code> || <code>TransferToCGRAM</code>
|-
| Supply a full address and let the macro extract the bank. || <code>TransferToVRAMFromAddr</code> || <code>TransferToCGRAMFromAddr</code>
|-
| Upload an entire resource registered in Dynamic Xtreme. || <code>TransferResourceToVRAM</code> || <code>TransferResourceToCGRAM</code>
|-
| Upload a specified number of bytes from a resource. || <code>TransferResourceToVRAMWithLenght</code> || <code>TransferResourceToCGRAMWithLenght</code>
|}

The normal versions check whether the transfer fits within the frame's byte limit:

* Carry set: the transfer was scheduled.
* Carry clear: the transfer was not scheduled because it would exceed the limit. Your code can retry in another frame.

This limit is shared by all Dynamic Xtreme uploads. Several transfers in one frame use the same allowance. These macros modify A and X. If accepted, the transfer leaves A, X, and Y in 8-bit mode; if rejected, A returns in 8-bit mode, but X and Y do not necessarily change size.

'''Transfer limits and requirements'''

Keep these limits in mind before preparing the inputs:

'''Byte budget and transfer list capacity'''

{| class="wikitable"
! Limit !! What it controls !! Default
|-
| <code>DX_Dynamic_MaxDataPerFrame</code>
| Total number of bytes that may be requested in one frame. Compared against <code>DX_Dynamic_CurrentDataSend</code>, which counts the bytes requested by all resources.
| <code>$0800</code> bytes, shared by Dynamic Xtreme uploads.
|-
| VRAM list
| Number of requests its tables can hold. Each entry uses two bytes per table; <code>!VRAMTransferSize</code> allocates the byte count for each table.
| <code>!VRAMTransferSize = 64</code>: room for '''32 requests'''.
|-
| CGRAM list
| Number of requests its tables can hold. <code>!CGRAMTransferSize</code> sets the number of available entries.
| <code>!CGRAMTransferSize = 64</code>: room for '''64 requests'''.
|}

These are separate limits. For example, 32 VRAM transfers of 2 bytes request only 64 bytes, but fill all 32 entries in the default list. You cannot add another request just because some byte budget remains.

Normal macros check '''the byte budget''', but '''do not check for a free list entry'''. If the list is full, your code must postpone the request. Adding it anyway can write beyond the tables and corrupt other variables; there is no separate failure result for a full list. Include requests from other systems in your count: a dynamic pose may require several transfers.

<code>Forced</code> variants skip the byte budget check and add the requested amount to <code>DX_Dynamic_CurrentDataSend</code>. They do not increase list capacity or the time available for transfers. List counters are 8-bit and the byte counter is 16-bit: do not let them overflow.

'''Transfer requirements'''

{| class="wikitable"
! Value !! Your code's responsibility
|-
| Length
| Use a '''positive, even''' byte count. In DMA, <code>$0000</code> means 65536 bytes, not an empty transfer. PPU macros do not check these conditions.
|-
| Source
| The resource or buffer must contain the requested number of bytes, without crossing a bank boundary. DMA does not continue automatically into the next bank. Split the upload if needed.
|-
| RAM source
| You must keep the buffer unchanged until NMI performs the transfer. The list stores its address, not a copy of its data. In SA-1, use memory that the S-CPU can also read, since it performs the transfer.
|-
| VRAM destination
| The address is measured in 2-byte words. Both the start and end must be within <code>$0000–$7FFF</code> and within the graphics space available to your resource. For example, <code>$0200</code> bytes starting at <code>$6000</code> occupy words <code>$6000–$60FF</code>.
|-
| CGRAM destination
| The destination specifies the first color. Each color occupies 2 bytes; the upload must not extend beyond color <code>$FF</code>. For example, 15 colors fit from <code>$F1</code> onward, or <code>$001E</code> bytes.
|}

Carry set from a normal macro means the request was accepted within the byte budget. It does not confirm that the source, destination, length, or list capacity was validated. These requirements also apply to <code>Forced</code> variants.

Use [[#Uploading_colors_with_TransferPalette|TransferPalette]] to change colors while updating SMW's palette copies and the effect state. PPU transfers to CGRAM only schedule the copy.

'''Register state'''

* Enter with 8-bit A, X, and Y. Normal versions set A to 16-bit mode internally to check the budget, but this entry state also supports <code>Forced</code> variants, especially CGRAM transfers.
* On acceptance, A and X change and all three registers return in 8-bit mode. Y is not used as a working register, but loses its high byte if you entered with 16-bit indices. On rejection, A changes and returns in 8-bit mode; X and Y retain their original values and sizes.
* Uses no scratch memory to prepare the request. Writes to the transfer lists and frame byte counter. Preserves DBR and D. DBR must allow access to the counter; some variants may also need that bank to read your memory operands.
* Source addresses and lengths are read with 16-bit A. The VRAM destination and bank argument are read with 16-bit A; supply the bank as a 16-bit value with a zero high byte. For CGRAM, the source bank and destination color are read with 8-bit A.
* X changes before several arguments are read. Do not pass X-indexed addresses assuming X will still hold the sprite index. Prefer immediate values or variables independent of X for transfer arguments.
* Includes neither <code>RTS</code> nor <code>RTL</code>. Execution continues after expansion. Check carry from normal variants before another operation changes it. <code>Forced</code> variants do not return a success flag in carry.

These rules also apply to <code>FromAddr</code>, <code>Resource</code>, and <code>WithLenght</code> variants: they prepare the arguments and expand the same transfer macro.

==== TransferToVRAM ====

<code>%TransferToVRAM()</code> schedules a graphics transfer from ROM or RAM to VRAM.

<pre>
%TransferToVRAM(VRAMOffset, ResourceAddr, ResourceBNK, Lenght)
</pre>

* <code>VRAMOffset</code>: VRAM destination address, measured in 2-byte words. For example, copying <code>$0200</code> bytes starting at <code>$6000</code> occupies words <code>$6000-$60FF</code>.
* <code>ResourceAddr</code>: source address within its bank.
* <code>ResourceBNK</code>: source bank.
* <code>Lenght</code>: number of bytes to copy. This spelling is retained because it is the parameter's actual name.

'''Example: scheduling a graphics upload'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToVRAM(#$6000, #!ResourceMyGraphics, #!ResourceMyGraphics>>16, #$0200)
BCC .NotLoaded
; The transfer will take place during the next NMI.
.NotLoaded
</pre>

<code>!ResourceMyGraphics</code> is the address of a resource registered through a DynamicInfo and written to <code>DXDefines.asm</code>. Its name is normalized by removing spaces, hyphens, and underscores and capitalizing each word: <code>my_graphics</code> becomes <code>MyGraphics</code>. The resource must contain the requested number of bytes.

==== TransferToVRAMFromAddr ====

Performs the same transfer, but takes the full source address. The macro separates the address and bank for you.

<pre>
%TransferToVRAMFromAddr(VRAMOffset, addr, Lenght)
</pre>

Write <code>addr</code> without <code>#</code>; supply the other parameters as in <code>TransferToVRAM</code>.

'''Example'''

<pre>
%TransferToVRAMFromAddr(#$6000, !ResourceMyGraphics, #$0200)
BCC .NotLoaded
.NotLoaded
</pre>

<code>!ResourceMyGraphics</code> is generated from a DynamicInfo resource and written to <code>DXDefines.asm</code>. Its name is normalized to PascalCase: <code>my_graphics</code> becomes <code>MyGraphics</code>.

==== TransferResourceToVRAM and TransferResourceToVRAMWithLenght ====

These variants take the name of a Dynamic Xtreme resource. The first copies the entire resource; the second copies the number of bytes you specify.

<pre>
%TransferResourceToVRAM(VRAMOffset, ResourceName)
%TransferResourceToVRAMWithLenght(VRAMOffset, ResourceName, Lenght)
</pre>

For a resource with defines <code>!ResourceMyGraphics</code> and <code>!ResourceMyGraphicsSize</code>, use <code>"MyGraphics"</code> as <code>ResourceName</code>.

'''Example: uploading the entire resource'''

<pre>
%TransferResourceToVRAM(#$6000, "MyGraphics")
BCC .NotLoaded
.NotLoaded
</pre>

'''Example: uploading only its first $0200 bytes'''

<pre>
%TransferResourceToVRAMWithLenght(#$6000, "MyGraphics", #$0200)
BCC .NotLoaded
.NotLoaded
</pre>

The name and size come from the defines generated in <code>DXDefines.asm</code> when installing DynamicInfo resources. Use the normalized name: <code>my_graphics</code> becomes <code>MyGraphics</code>, with separators removed and each word capitalized.

==== TransferToCGRAM ====

<code>%TransferToCGRAM()</code> schedules a color transfer from ROM or RAM to a SNES palette.

<pre>
%TransferToCGRAM(CGRAMOffset, TableAddr, TableBNK, Lenght)
</pre>

* <code>CGRAMOffset</code>: first destination color number, from <code>$00</code> to <code>$FF</code>. For example, palette 8 starts at color <code>$80</code>.
* <code>TableAddr</code> and <code>TableBNK</code>: address and bank of the colors to copy.
* <code>Lenght</code>: byte count. Each color occupies 2 bytes; 15 colors occupy <code>$001E</code> bytes.

Source colors must use the standard SNES BGR555 format. If you calculated an effect, use its final 2-byte-per-color result, such as the output of an <code>AndMerge</code> variant.

'''Example: copying palette 8's 15 visible colors'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToCGRAM(#$81, #DX_PPU_CGRAM_PaletteWriteMirror+$0102, #DX_PPU_CGRAM_PaletteWriteMirror>>16, #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

This example uses an effect result stored in <code>DX_PPU_CGRAM_PaletteWriteMirror</code>. Offset <code>$0102</code> corresponds to color <code>$81</code>, since each color occupies 2 bytes. It skips the palette's first color, which is transparent for sprites.

==== TransferToCGRAMFromAddr ====

Performs the same color transfer, but takes the full source address. Write <code>addr</code> without <code>#</code>.

<pre>
%TransferToCGRAMFromAddr(CGRAMOffset, addr, Lenght)
</pre>

'''Example'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToCGRAMFromAddr(#$81, DX_PPU_CGRAM_PaletteWriteMirror+$0102, #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

The result is the same as in the previous example: schedules an upload of 15 colors starting at palette 8's second color.

==== TransferResourceToCGRAM and TransferResourceToCGRAMWithLenght ====

These variants copy colors from a resource registered in Dynamic Xtreme. The first uses the full resource size; the second uses the byte count you specify.

<pre>
%TransferResourceToCGRAM(CGRAMOffset, ResourceName)
%TransferResourceToCGRAMWithLenght(CGRAMOffset, ResourceName, Lenght)
</pre>

'''Example: copying an entire color resource'''

<pre>
%TransferResourceToCGRAM(#$80, "MyColors")
BCC .NotLoaded
.NotLoaded
</pre>

'''Example: copying only 15 colors'''

<pre>
%TransferResourceToCGRAMWithLenght(#$81, "MyColors", #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

These examples assume a general color resource with defines <code>!ResourceMyColors</code> and <code>!ResourceMyColorsSize</code>, generated in <code>DXDefines.asm</code> from a DynamicInfo. Use the normalized name: <code>my_colors</code> becomes <code>MyColors</code>. In the second example, the resource must begin with the 15 colors to copy, without a transparent color before them.

==== Forced variants ====

All transfers above have a variant whose name begins with <code>Forced</code>. These schedule the transfer even if it exceeds the frame's byte limit. The byte count is still added to the frame's total.

{| class="wikitable"
! VRAM !! CGRAM
|-
| <code>ForcedTransferToVRAM</code> || <code>ForcedTransferToCGRAM</code>
|-
| <code>ForcedTransferToVRAMFromAddr</code> || <code>ForcedTransferToCGRAMFromAddr</code>
|-
| <code>ForcedTransferResourceToVRAM</code> || <code>ForcedTransferResourceToCGRAM</code>
|-
| <code>ForcedTransferResourceToVRAMWithLenght</code> || <code>ForcedTransferResourceToCGRAMWithLenght</code>
|}

They take the same parameters as the versions without <code>Forced</code>. Carry does not report whether the transfer was accepted. Set A to 8-bit mode before using them; A, X, and Y return in 8-bit mode.

'''Example'''

<pre>
%ForcedTransferResourceToVRAM(#$6000, "MyGraphics")
; Do not check carry for this variant.
</pre>

<code>MyGraphics</code> corresponds to the DynamicInfo resource <code>!ResourceMyGraphics</code> in <code>DXDefines.asm</code>. Use the normalized name, as in <code>my_graphics</code> → <code>MyGraphics</code>.

Use <code>Forced</code> for uploads that need priority and whose data size you already control. Forcing too much data can exceed the time available for graphics updates. For other uploads, use the normal variants and check carry.

=== Math ===

These macros multiply and divide using SNES or SA-1 hardware, depending on the ROM. They use unsigned numbers: values represent positive quantities or zero.

Set A to 8-bit mode before calling them. The macros do not change the size of A, X, or Y for you.

'''Registers and temporary memory:''' all macros in this category, including <code>W</code> and <code>After...</code> variants, modify A and N/Z, preserve X, Y, carry, DBR, and D, and use no scratch memory. They retain their entry register sizes; A must be 8-bit for correct hardware writes. DBR must allow access to the SNES or SA-1 arithmetic registers as appropriate. Includes neither <code>RTS</code> nor <code>RTL</code>; execution continues after the macro. Results are in the hardware registers listed below, not in A. Carry does not report success or arithmetic overflow.

'''Writing the arguments'''

<code>Mul</code>, <code>Div</code>, <code>MulAfterMul</code>, and <code>DivAfterDiv</code> append the argument directly to <code>LDA</code>. Put the argument in quotation marks with a leading space: <code>" #$05"</code> produces <code>LDA #$05</code>.

You can also start the argument with <code>.b</code>, <code>.w</code>, or <code>.l</code> to select the memory access encoding. For example, if <code>$02</code> holds the number to multiply:

<pre>
%Mul(".b $02", " #$07")
</pre>

This generates <code>LDA.b $02</code> to read the first number and <code>LDA #$07</code> for the second. These suffixes control address encoding; they do not change A's size. The multiplication still uses 8-bit numbers.

Variants with <code>W</code>, along with <code>MulAfterDiv</code> and <code>DivAfterMul</code>, already add a space before their arguments. Write their values normally, as in <code>%MulW(#$05, #$07)</code>. The current implementation does not accept <code>.b</code>, <code>.w</code>, or <code>.l</code> suffixes in the same way for these variants, because the inserted space would separate <code>LDA</code> from the suffix.

'''What does W mean?'''

The hardware needs a short time to finish the calculation. Macros with <code>W</code> include that wait, so you can read the result immediately afterward. Versions without <code>W</code> let you run other code while the hardware calculates, but you must allow enough time before reading the result. Use a <code>W</code> variant if you need the result in the next instruction.

Read results through these defines:

* <code>!MultiplicationResult</code>: 16-bit multiplication result.
* <code>!DivisionResult</code>: 16-bit division quotient.
* <code>!RemainderResult</code>: 16-bit division remainder.

These defines select the correct SNES or SA-1 address. The next calculation may overwrite previous results; save them if you need them later.

==== Mul and MulW ====

Multiply two 8-bit values to produce a 16-bit result.

<pre>
%Mul(a, b)
%MulW(a, b)
</pre>

<code>a</code> and <code>b</code> can be immediate values, such as <code>#$06</code>, or 8-bit variables.

'''Example: 6 × 7 = 42'''

<pre>
%MulW(#$06, #$07)
REP #$20
LDA !MultiplicationResult ; A = $002A, or 42
SEP #$20
</pre>

The call without a wait is <code>%Mul(" #$06", " #$07")</code>. Do not read its result immediately: first run other code that does not use the multiplication or division hardware.

==== Div and DivW ====

Divide a 16-bit number by an 8-bit number. Supply the 16-bit number as two bytes: high byte first, then low byte.

<pre>
%Div(ah, al, b)
%DivW(ah, al, b)
</pre>

* <code>ah</code>: high byte of the number to divide.
* <code>al</code>: low byte of the same number.
* <code>b</code>: divisor, from 1 to 255.

'''Example: 300 ÷ 7 = 42, remainder 6'''

<pre>
; 300 = $012C: high byte $01, low byte $2C.
%DivW(#$01, #$2C, #$07)

REP #$20
LDA !DivisionResult ; A = $002A, or 42
LDA !RemainderResult ; A = $0006
SEP #$20
</pre>

You can also pass a 16-bit variable as two arguments: <code>%DivW(MiNumero+1, MiNumero, #$07)</code>. Here, <code>MiNumero</code> represents a variable defined by your code.

==== Continuing from the previous result ====

<code>AfterMul</code> and <code>AfterDiv</code> variants use the previous calculation's result as the first number. You only need to supply the second number.

{| class="wikitable"
! Macro !! Calculation
|-
| <code>MulAfterMul(b)</code> / <code>MulWAfterMul(b)</code> || Multiplies the low 8 bits of the previous multiplication result by b.
|-
| <code>MulAfterDiv(b)</code> / <code>MulWAfterDiv(b)</code> || Multiplies the low 8 bits of the previous quotient by b.
|-
| <code>DivAfterMul(b)</code> / <code>DivWAfterMul(b)</code> || Divides the full previous multiplication result by b.
|-
| <code>DivAfterDiv(b)</code> / <code>DivWAfterDiv(b)</code> || Divides the full previous quotient by b.
|}

W still means the new result can be read immediately afterward. <code>After...</code> variants already include the wait needed to read the previous calculation's result.

'''Example: two multiplications, (6 × 7) × 2 = 84'''

<pre>
%Mul(" #$06", " #$07")
%MulWAfterMul(#$02)
REP #$20
LDA !MultiplicationResult ; A = $0054, or 84
SEP #$20
</pre>

'''Example: division followed by multiplication, (100 ÷ 4) × 3 = 75'''

<pre>
%Div(" #$00", " #$64", " #$04")
%MulWAfterDiv(#$03)
REP #$20
LDA !MultiplicationResult ; A = $004B, or 75
SEP #$20
</pre>

'''Example: multiplication followed by division, (20 × 15) ÷ 4 = 75'''

<pre>
%Mul(" #$14", " #$0F")
%DivWAfterMul(#$04)
REP #$20
LDA !DivisionResult ; A = $004B, or 75
SEP #$20
</pre>

'''Example: two divisions, (300 ÷ 3) ÷ 4 = 25'''

<pre>
%Div(" #$01", " #$2C", " #$03")
%DivWAfterDiv(#$04)
REP #$20
LDA !DivisionResult ; A = $0019, or 25
SEP #$20
</pre>

In multiplication, the first number is always limited to 8 bits. If the previous result exceeds 255, <code>MulAfterMul</code> or <code>MulAfterDiv</code> uses only its low byte. The division macros in this table use the full 16-bit previous result.

Dynamic Xtreme UberASM guide

2026-10-25T21:57:21Z

Anonimzwx: Created page with "{{Select Language|Dynamic_Xtreme_UberASM_guide}} This article explains how to use Dynamic Xtreme from UberASM to configure a level's resources and change graphics and colors during gameplay. Examples cover restricting palettes, choosing VRAM space for dynamic sprites, creating animations, and changing the player's graphics. == Requirements == * Have UberASMTool installed and configured to insert code into your ROM. * Have Dynamic Xtreme installed with the features req..."

{{Select Language|Dynamic_Xtreme_UberASM_guide}}

This article explains how to use Dynamic Xtreme from UberASM to configure a level's resources and change graphics and colors during gameplay. Examples cover restricting palettes, choosing VRAM space for dynamic sprites, creating animations, and changing the player's graphics.

== Requirements ==

* Have UberASMTool installed and configured to insert code into your ROM.
* Have Dynamic Xtreme installed with the features required by your chosen example. See the [[Dynamic_Xtreme_Quick_Start|Quick Start guide]] for installation.

See the [[Dynamic_Xtreme_ASM_API|ASM API reference]] for call parameters and variable usage.

Each example requires the following features:

{| class="wikitable"
! Example !! Required features
|-
| [[#Setting_aside_palettes_for_other_resources|Setting aside palettes for other resources]]
| <code>PalettesChange</code>.
|-
| [[#Choosing_VRAM_space_for_dynamic_sprites|Choosing VRAM space for dynamic sprites]]
| <code>GraphicsChange</code> and <code>DynamicPoses</code>. Drawing these poses with Dynamic Xtreme also requires <code>DrawingSystem</code>.
|-
| [[#Setting_the_transfer_limit_per_frame|Setting the transfer limit per frame]]
| <code>GraphicsChange</code> for graphics uploads or <code>PalettesChange</code> for palette uploads; both if you use both types.
|-
| [[#Creating_graphics_animations|Creating graphics animations]]
| <code>GraphicsChange</code> and <code>PalettesChange</code>, since the example uploads graphics and a palette. Add <code>PalettesEffects</code> if you set <code>!PaletteGlobalEffect</code> to 1 to use the global effect.
|-
| [[#Changing_palettes_during_gameplay|Changing palettes during gameplay]]
| <code>PalettesChange</code> and, with <code>!PaletteGlobalEffect = 1</code> as in the example, <code>PalettesEffects</code>. To upload without the global effect, use <code>!PaletteGlobalEffect = 0</code>; only <code>PalettesChange</code> is then required.
|-
| [[#Changing_the_player's_graphics|Changing the player's graphics]]
| <code>PlayerFeatures</code> and its dependencies, <code>GraphicsChange</code> and <code>PalettesChange</code>.
|-
| [[#Applying_a_global_palette_effect|Applying a global palette effect]], fixed, cyclic, or transitional
| <code>PalettesChange</code> and <code>PalettesEffects</code>.
|}

The graphics animation in this guide copies data to a fixed VRAM destination: it does not require <code>DynamicPoses</code> or <code>DrawingSystem</code>. See the [[Dynamic_Xtreme_ASM_API#Features_required_to_use_the_API|API feature table]] for the routines and macros enabled by each feature.

== Preparing the examples ==

Each example stands on its own. Save the level code in the appropriate UberASMTool folder and add it to the list. If you combine examples in one file, merge their <code>load</code>, <code>init</code>, and <code>main</code> blocks so the labels are not duplicated.

* <code>load</code> prepares data while the level loads.
* <code>init</code> sets options when entering the level. The palette restriction example uses this block.
* <code>main</code> runs during gameplay, once per frame.

Dynamic Xtreme defines and macros must be available in UberASMTool through the integration performed during installation. Declare any additional graphics, palettes, or effects in the ASM using the corresponding includes:

<pre>
;#incdyn "DynamicXtreme/MyResources.dynamicinfo"
;#incpale "DynamicXtreme/MyEffect.paleffect"
</pre>

Paths are relative to the ASM file. Include only files used by your example. You can also use Dynamic Xtreme's traditional folders, as explained in [[Dynamic_Xtreme_files_and_formats|Files and formats]].

After adding or modifying these resources, install Dynamic Xtreme first, then UberASMTool. If you only change the ASM logic, rerun UberASMTool.

Names beginning with <code>RAM_LIBRE_...</code> in these examples are placeholders: replace them with free RAM addresses before inserting the code. They are not Dynamic Xtreme defines. Allocate the specified number of bytes and use separate addresses for variables that must coexist. Check that the game, Dynamic Xtreme, Lunar Magic, and other resources do not use them; an address free in the original SMW may already be in use in your ROM. You can look for addresses in the [https://www.smwcentral.net/?p=memorymap&game=smw&u=0&address=&sizeOperation=%3D&sizeValue=&region%5B%5D=ram&type=Empty&description= SMW Central RAM map filtered to empty space].

If you use a short SMW RAM address outside '''direct page''', add <code>|!addr</code> for the appropriate LoROM or SA-1 remapping. For example, when choosing the timer address:

<pre>
!AnimationTimer = RAM_LIBRE_ANIM_TIMER|!addr
</pre>

Replace <code>RAM_LIBRE_ANIM_TIMER</code> with your chosen address and keep <code>|!addr</code>. Direct page addresses use the execution context's D base and do not use this remapping. If you choose a full 24-bit address, check its bank and whether the example's instructions can access it; <code>|!addr</code> is intended here for short addresses outside direct page.

== Setting aside palettes for other resources ==

If an animation, HUD, or other resource needs a fixed palette, set it aside so Dynamic Xtreme does not choose it when assigning palettes to dynamic sprites.

Write <code>$FFFE</code> to its <code>DX_Dynamic_Palettes_ID</code> entry. Each entry occupies 2 bytes. For example, palette 9 uses offset <code>$12</code>: 9 × 2.

See [[Dynamic_Xtreme_ASM_API#Palettes_and_the_global_effect|Palettes and the global effect in the API]] for an explanation of this table.

<pre>
init:
REP #$20
LDA #$FFFE
STA.l DX_Dynamic_Palettes_ID+$12 ; Set aside palette 9
SEP #$20
RTL
</pre>

To set aside several palettes, write the same value to each entry:

{| class="wikitable"
! Palette !! Offset
|-
| 8 || <code>$10</code>
|-
| 9 || <code>$12</code>
|-
| A || <code>$14</code>
|-
| B || <code>$16</code>
|-
| C || <code>$18</code>
|-
| D || <code>$1A</code>
|-
| E || <code>$1C</code>
|-
| F || <code>$1E</code>
|}

This prevents automatic assignment from claiming the palette; it does not upload colors. A resource configured to use it manually can still change its colors, so do not also assign it to another resource that needs a different palette.

== Choosing VRAM space for dynamic sprites ==

Dynamic sprites need VRAM space for their poses. Choose a region not used by the level's static graphics.

The [[SMW_VRAM_Map#Levels|SMW VRAM map on SNESLab]] shows the regions corresponding to SP1, SP2, SP3, and SP4.

For example, to allow SP4:

[[Dynamic_Xtreme_ASM_API#DynamicPoseSpaceConfig|DynamicPoseSpaceConfig]] takes one of the predefined configurations.

<pre>
init:
LDA #!DynamicSpaceConfigSP4
JSL !DynamicPoseSpaceConfig
RTL
</pre>

If you need more space and the level allows it, choose <code>!DynamicSpaceConfigSP34</code> for SP3 and SP4, or <code>!DynamicSpaceConfigSP234</code> for SP2, SP3, and SP4. Other options include half pages and configurations that share space with the player or DSX.

The available defines are listed in <code>DXDefines.asm</code> and the [[Dynamic_Xtreme_ASM_API#Space_configurations_for_dynamic_poses|API configuration table]]. Set the configuration before the level starts loading poses; changing it does not automatically remove poses already in VRAM.

=== Creating a custom configuration ===

Use [[Dynamic_Xtreme_ASM_API#DefineDynamicSpaceConfig|DefineDynamicSpaceConfig]] to combine regions differently. This example makes the first half of SP3 and all of SP4 available, restricting everything else:

<pre>
init:
; Restrict SP1 and SP2.
%DefineDynamicSpaceConfig($00, $3F, $80)

; Make the first half of SP3 available.
%DefineDynamicSpaceConfig($40, $4F, $00)

; Restrict the second half of SP3.
%DefineDynamicSpaceConfig($50, $5F, $80)

; Make SP4 available.
%DefineDynamicSpaceConfig($60, $7F, $00)
RTL
</pre>

The first two parameters are the first and last 16×16 blocks, both inclusive. The third is <code>$00</code> to allow dynamic poses or <code>$80</code> to restrict the region. IDs run left to right and top to bottom, with 8 blocks per row. The [[Dynamic_Xtreme_ASM_API#DefineDynamicSpaceConfig|macro documentation]] includes the full numbering table.

This replaces the preset configuration call; do not run both configurations in sequence. Adjust the ranges to cover blocks <code>$00–$7F</code> without overlaps, and restrict regions needed by other level graphics. Like the previous example, this requires <code>GraphicsChange</code> and <code>DynamicPoses</code>.

== Setting the transfer limit per frame ==

<code>DX_Dynamic_MaxDataPerFrame</code> sets how many bytes normal Dynamic Xtreme uploads may schedule in a frame. Dynamic poses, animations, and other transfers using its macros share this limit.

See these variables in [[Dynamic_Xtreme_ASM_API#Counters_and_data_per_frame|Counters and data per frame in the API]].

The default is <code>$0800</code>, or 2048 bytes. This example increases it to <code>$0A00</code>, or 2560 bytes:

<pre>
init:
REP #$20
LDA #$0A00
STA.l DX_Dynamic_MaxDataPerFrame
SEP #$20
RTL
</pre>

Increasing it allows more uploads to be requested in one frame, but does not give the SNES more time to perform them. Too much data can cause visual problems. Adjust the value for your level and test with its sprites and animations running together.

Normal macros return carry clear if an upload does not fit within the limit. Keep the current graphics or colors and retry later. <code>Forced</code> variants skip the check and still add their bytes to the total.

== Creating graphics animations ==

This example creates a graphics animation: a table gives each image's starting address, a timer controls when to change images, and the previous image stays in place if the transfer is rejected.

It uses [[Dynamic_Xtreme_ASM_API#TransferToVRAM|TransferToVRAM]] for graphics changes, its [[Dynamic_Xtreme_ASM_API#Forced_variants|Forced variant]] for the initial upload, and [[Dynamic_Xtreme_ASM_API#TransferPaletteResource|TransferPaletteResource]] for colors. Follow those links for parameters, registers, and results.

Declare the example's files in <code>DynamicXtreme/SMMArrow.dynamicinfo</code>:

<pre>
Resources:
SMMArrow.bin
Palettes:
SMMArrowPal.bin
</pre>

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incdyn "DynamicXtreme/SMMArrow.dynamicinfo"

; Choose free RAM here: one separate byte per variable.
!CurrentPoseIndex = RAM_LIBRE_ANIM_POSE
!AnimationTimer = RAM_LIBRE_ANIM_TIMER
!PaletteLoaded = RAM_LIBRE_ANIM_PALETA

; Frames to wait before attempting the next change.
!TimePerPose = $03

; Bytes per image: one 8x8 4bpp tile occupies $0020.
!DataSend = $0200

; Number of images used.
!NumberOfPoses = $05

; Source: installed resource. You can also use !AN2Buffer2.
!Source = !ResourceSMMArrow

; VRAM destination address.
!Destination = !BG2Line0

; Installed palette and first destination color.
!Palette = "SMMArrowPal"
!PaletteDestination = $71

; 0 = no global effect; 1 = apply the global effect.
!PaletteGlobalEffect = 0

init:
STZ !CurrentPoseIndex
LDA #!TimePerPose
STA !AnimationTimer
STZ !PaletteLoaded

%ForcedTransferToVRAM(#!Destination, #!Source, #((!Source>>16)&$FF), #!DataSend)
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCC .Return
LDA #$01
STA !PaletteLoaded
.Return
RTL

main:
; Retry the palette if init's upload was rejected.
LDA !PaletteLoaded
BNE .Animate
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCS .PaletteReady
RTL
.PaletteReady
LDA #$01
STA !PaletteLoaded

.Animate
LDA !AnimationTimer
BEQ .NextPose
DEC !AnimationTimer
RTL

.NextPose
LDA !CurrentPoseIndex
INC A
CMP #!NumberOfPoses
BCC .SelectPose
LDA #$00
.SelectPose
STA $05
ASL
TAX

REP #$20
LDA.l PosesTable,x
CLC
ADC.w #!Source
STA $00
SEP #$20

%TransferToVRAM(#!Destination, $00, #((!Source>>16)&$FF), #!DataSend)
BCC .Return

LDA $05
STA !CurrentPoseIndex
LDA #!TimePerPose
STA !AnimationTimer
.Return
RTL

PosesTable:
dw $0000
dw !DataSend*$01
dw !DataSend*$02
dw !DataSend*$03
dw !DataSend*$04
</pre>

'''What you can customize'''

* <code>!TimePerPose</code>: wait time. With <code>$03</code>, a change is attempted every four frames: three to count down the timer and one to make the change.
* <code>!DataSend</code>: bytes per image. <code>$0200</code> is 16 8×8 tiles in 4bpp.
* <code>!NumberOfPoses</code> and <code>PosesTable</code>: image count and offsets within the source. The example uses the first five images in <code>SMMArrow.bin</code>. Extend the table if you add more.
* <code>!Source</code>: graphics address. The example reads <code>!ResourceSMMArrow</code> directly; use <code>!AN2Buffer2</code> to animate graphics already prepared by Lunar Magic.
* <code>!Destination</code>: VRAM region to update. Place tiles in the level that use this region, and check that another resource does not overwrite it.
* <code>!Palette</code>, <code>!PaletteDestination</code>, and <code>!PaletteGlobalEffect</code>: palette resource, first destination color, and participation in the global effect.

Replace the three RAM placeholders at the start with addresses available throughout the level: each variable needs its own byte. These are not temporary scratch bytes. <code>!PaletteLoaded</code> lets the code retry a rejected palette upload without repeating it once accepted.

<code>!ResourceSMMArrow</code>, <code>!PaletteSMMArrowPal</code>, and <code>!PaletteSMMArrowPalSize</code> are generated when installing the DynamicInfo and written to <code>DXDefines.asm</code>. Their names are normalized to PascalCase by removing separators; here, the capitalization in <code>SMMArrow</code> and <code>SMMArrowPal</code> is preserved.

All images used must be in the same source bank. The initial graphics upload uses <code>Forced</code>; later changes respect the frame's data limit. If an upload is rejected, the code keeps the previous image and retries next frame without advancing the index or resetting the timer.

The timer advances each time <code>main</code> runs. To stop the animation while paused or while the action is frozen, check <code>$13D4|!addr</code> and <code>$9D</code> before counting it down.

== Changing palettes during gameplay ==

<code>TransferPalette</code> macros upload colors while keeping SMW's and Dynamic Xtreme's palette copies up to date. They also prepare palette effects, so you do not need to copy buffers or clear flags manually.

This example uses [[Dynamic_Xtreme_ASM_API#TransferPaletteResource|TransferPaletteResource]]; see its API entry for the parameters and carry results.

The example uses <code>SMMArrowPal.bin</code>, a 15-color file (<code>$001E</code> bytes), and changes colors 1–F of palette 7. Color 0 is left unchanged.

In <code>DynamicXtreme/SMMArrow.dynamicinfo</code>, declare the graphics as a general resource and the palette under <code>Palettes</code>:

<pre>
Resources:
SMMArrow.bin
Palettes:
SMMArrowPal.bin
</pre>

In the level ASM:

<pre>
;#incdyn "DynamicXtreme/SMMArrow.dynamicinfo"

; Choose one byte of free RAM here.
!PaletteChangePending = RAM_LIBRE_CAMBIO_PALETA

!Palette = "SMMArrowPal"
!PaletteDestination = $71
!PaletteGlobalEffect = 1

init:
LDA #$01
STA !PaletteChangePending
; Continue to the first upload attempt.

main:
LDA !PaletteChangePending
BNE .TryTransfer
RTL

.TryTransfer
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCC .Return

; Confirm the change only if the call was accepted.
STZ !PaletteChangePending
.Return
RTL
</pre>

Replace <code>RAM_LIBRE_CAMBIO_PALETA</code> with one byte of free RAM available throughout the level. <code>!PaletteChangePending</code> is set to 1 when a change is requested and returns to 0 only when the macro returns carry set. If the call fails, the change remains pending and is retried next frame. Once accepted, the upload is not repeated.

<code>!Palette</code> selects the resource, and <code>!PaletteDestination</code> selects the first destination color. <code>!PaletteGlobalEffect</code>, the macro's last parameter, controls the upload:

* <code>1</code>: prepares the original colors so they receive the global effect before being displayed. Also prepares the palette if no effect has been selected yet.
* <code>0</code>: uploads the colors without the global effect and excludes that palette from it. Also updates SMW's buffers, which prevents palette corruption during the goal victory animation.

To upload the same palette without the global effect, change only this define and keep the carry check:

<pre>
!PaletteGlobalEffect = 0
</pre>

If effects are disabled in the installation, both options upload directly. When effects are enabled and you use <code>1</code>, the system uploads the processed result; it does not display an unaffected palette for one frame first.

<code>SMMArrowPal</code> uses <code>!PaletteSMMArrowPal</code> and <code>!PaletteSMMArrowPalSize</code>, generated from the DynamicInfo's <code>Palettes</code> section and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase by removing separators and capitalizing each word. In this case, <code>SMMArrowPal</code> stays as written.

To request another change during gameplay, set <code>!PaletteChangePending</code> to 1 when your chosen condition is met. Do not set it every frame if the palette is unchanged. For a direct upload, carry set means the transfer was scheduled; with the global effect, it means the original colors were prepared, not that the result is already visible.

The effect option applies to the entire 16-color palette. When uploading colors for a global effect, prepare all visible colors, as with the 15 in this example; do not change just a few colors expecting to preserve a base you have not prepared yet.

If you use a fixed sprite palette from 8–F, set it aside first as described at the start of this article. These macros do not perform automatic assignment. To upload from an address, pointer, or table, see [[Dynamic_Xtreme_ASM_API#Uploading_colors_with_TransferPalette|Uploading colors with TransferPalette in the API]].

== Changing the player's graphics ==

This example switches between the original player and Geno when you press up. Its defines let you choose the graphics and four palettes: Mario, Luigi, Fire Mario, and Fire Luigi. It also updates the selected palette when the player's state changes.

Requires <code>PlayerFeatures</code>. Custom graphics must use the same pose layout as the originals; changing the source does not adapt a spritesheet with a different layout.

The code uses the [[Dynamic_Xtreme_ASM_API#Player_and_Yoshi|player variables]] and macros [[Dynamic_Xtreme_ASM_API#Div_and_DivW|DivW]], [[Dynamic_Xtreme_ASM_API#TransferPaletteFromPointer|TransferPaletteFromPointer]], and [[Dynamic_Xtreme_ASM_API#TransferPaletteFromAddress|TransferPaletteFromAddress]]. Their API entries explain each call's parameters, registers, and results.

Declare the following in <code>DynamicXtreme/Geno.dynamicinfo</code>:

<pre>
Resources:
Geno.bin
Palettes:
GenoPal.bin
GenoPalPlayer2.bin
FireGenoPal.bin
FireGenoPalPlayer2.bin
</pre>

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incdyn "DynamicXtreme/Geno.dynamicinfo"

; Choose two consecutive bytes of free RAM here.
!Last0D82 = RAM_LIBRE_JUGADOR_2_BYTES

; Custom player graphics.
!PlayerGFXResource = !ResourceGeno

; Palettes: player 1, player 2, and their fire variants.
!PlayerGFXPalette = !PaletteGenoPal
!PlayerGFXPalettePlayer2 = !PaletteGenoPalPlayer2
!PlayerGFXFirePalette = !PaletteFireGenoPal
!PlayerGFXFirePalettePlayer2 = !PaletteFireGenoPalPlayer2

; Switch button: $08 = up.
!ChangeButton = $08

init:
REP #$20
LDA $0D82|!addr
STA !Last0D82
SEP #$20

main:
LDA !ButtonDown_BYETUDLR
AND #!ChangeButton
BNE .Change

REP #$20
LDA $0D82|!addr
CMP !Last0D82
BNE .Reload
SEP #$20
RTL

.Change
LDA.l DX_Dynamic_Player_GFX_BNK
CMP.b #!GFX32Buffer>>16
BEQ .ChooseGeno
JMP .Mario
.ChooseGeno
JMP .Geno

.Reload
SEP #$20
LDA.l DX_Dynamic_Player_GFX_BNK
CMP.b #!GFX32Buffer>>16
BNE .Geno
JMP .Mario

.Geno
; Get 0, 1, 2, or 3 based on the player and fire state.
REP #$20
LDA $0D82|!addr
SEC
SBC #!PlayerBasePalette
STA $00
SEP #$20
%DivW($01, $00, #$14)

; Each address in GenoPals occupies three bytes.
LDA !DivisionResult
ASL
CLC
ADC !DivisionResult
TAX

; Keep the selected source and prepare colors 2-5.
REP #$20
LDA.l GenoPals,x
STA $03
CLC
ADC #$0002
STA $00
SEP #$20
LDA.l GenoPals+2,x
STA $02
STA $05

%TransferPaletteFromPointer($00, #$82, $0008, 0)
BCS .ApplyGeno
RTL

.ApplyGeno
REP #$20
LDA.w #!PlayerGFXResource
STA.l DX_Dynamic_Player_GFX_Addr
LDA.w #(!PlayerGFXResource>>16)&$00FF
STA.l DX_Dynamic_Player_GFX_BNK

; The player routine uploads colors 6-F.
LDA $03
CLC
ADC #$000A
STA.l DX_Dynamic_Player_Palette_Addr
SEP #$20
LDA $05
STA.l DX_Dynamic_Player_Palette_BNK
JMP .ConfirmSelection

.Mario
%TransferPaletteFromAddress(!PlayerPaletteColor2To5, #$82, $0008, 0)
BCS .ApplyMario
RTL

.ApplyMario
REP #$20
LDA.w #!GFX32Buffer
STA.l DX_Dynamic_Player_GFX_Addr
LDA $0D82|!addr
STA.l DX_Dynamic_Player_Palette_Addr
LDA.w #(!GFX32Buffer>>16)&$00FF
STA.l DX_Dynamic_Player_GFX_BNK
LDA #$0000
STA.l DX_Dynamic_Player_Palette_BNK
SEP #$20

.ConfirmSelection
REP #$20
LDA $0D82|!addr
STA !Last0D82
SEP #$20
RTL

GenoPals:
dl !PlayerGFXPalette
dl !PlayerGFXPalettePlayer2
dl !PlayerGFXFirePalette
dl !PlayerGFXFirePalettePlayer2
</pre>

'''What you can customize'''

* <code>!PlayerGFXResource</code>: custom character graphics.
* The four <code>!PlayerGFX...Palette...</code> defines: palette addresses, in the order used by <code>GenoPals</code>.
* <code>!ChangeButton</code>: button used to switch characters. Uses the controller bits <code>BYETUDLR</code>; <code>$08</code> is up.
* <code>!Last0D82</code>: replace <code>RAM_LIBRE_JUGADOR_2_BYTES</code> with two consecutive free RAM bytes. This stores the game's palette selection; neither byte may be used by other code.

<code>!ResourceGeno</code>, <code>!PaletteGenoPal</code>, <code>!PaletteGenoPalPlayer2</code>, <code>!PaletteFireGenoPal</code>, and <code>!PaletteFireGenoPalPlayer2</code> are generated from the DynamicInfo and written to <code>DXDefines.asm</code>. Names use PascalCase, with spaces, hyphens, and underscores removed and existing capitals preserved.

Each palette file contains colors 1–F. Its first color is skipped to copy colors 2–5; the final ten start at <code>+$0A</code> and are used by the player routine.

Colors 2–5 are uploaded with <code>TransferPalette</code>, which also updates SMW's buffers. The example does not confirm a graphics change if that transfer is rejected. A pending player-state change is retried while it differs from <code>!Last0D82</code>; if a button-requested change is rejected, press the button again.

The code identifies the original player by the bank of <code>!GFX32Buffer</code>. If you adapt it to switch between several custom characters in ROM, you will need another way to track the selected character.

This example uploads the player's palette without the global effect. Changing a four-color upload's parameter to <code>1</code> is not enough to add an effect: you must prepare all visible colors of palette 8 and account for its special upload handling.

== Applying a global palette effect ==

These examples apply a fixed effect, cycle through effects, or run a transition that stops when finished. You can select each palette separately and include the fixed color. The cycle and transition examples also let you set the speed with <code>!Delay</code>.

All three configure the [[Dynamic_Xtreme_ASM_API#Palettes_and_the_global_effect|global effect variables]] and the [[Dynamic_Xtreme_ASM_API#Fixed_color_and_the_first_palette_color|fixed color and first palette color variables]]. Their API entries explain each variable.

In <code>*.paleffect</code> files, <code>EffectType</code> selects the effect type. Ratios range from 0 to 127, and <code>Channel</code> values range from 0 to 31.

=== Choosing the affected palettes ===

In each example, set <code>!P0</code> through <code>!PF</code> to 1 to include the corresponding palette or 0 to exclude it. <code>!EnableFixedColor</code> controls the fixed color, and <code>!EnableColor00</code> includes color 0,0.

The masks <code>!EnableBG</code>, <code>!EnableSP</code>, and <code>!EnableColors</code> are calculated from these settings. You do not need to edit them manually. In the current API, the lowest bit corresponds to the first palette in each group:

{| class="wikitable"
! Bit value !! Background palette !! Sprite palette
|-
| <code>$01</code> || 0 || 8
|-
| <code>$02</code> || 1 || 9
|-
| <code>$04</code> || 2 || A
|-
| <code>$08</code> || 3 || B
|-
| <code>$10</code> || 4 || C
|-
| <code>$20</code> || 5 || D
|-
| <code>$40</code> || 6 || E
|-
| <code>$80</code> || 7 || F
|}

The fixed color and color 0,0 use <code>DX_PPU_ColorEffect_Enable</code>: bits <code>$01</code> and <code>$02</code>, respectively.

For sprites with dynamic assignment, also configure the E bit in <code>PaletteOption</code>. When using <code>TransferPalette</code>, its last parameter controls whether those palettes participate in the global effect. Avoid having other code overwrite the masks without accounting for this configuration.

=== Applying a fixed effect ===

This example applies the effect selected by <code>!PaletteEffetID</code>. The configuration shown enables all palettes and the fixed color, and selects the last effect in <code>DecreaseSaturation</code>.

Save the following in <code>DynamicXtreme/DecreaseSaturation.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel2": 0, "Ratio2": 4, "EffectType": 11},
{"Channel2": 0, "Ratio2": 8, "EffectType": 11},
{"Channel2": 0, "Ratio2": 12, "EffectType": 11},
{"Channel2": 0, "Ratio2": 16, "EffectType": 11},
{"Channel2": 0, "Ratio2": 20, "EffectType": 11},
{"Channel2": 0, "Ratio2": 25, "EffectType": 11},
{"Channel2": 0, "Ratio2": 29, "EffectType": 11},
{"Channel2": 0, "Ratio2": 33, "EffectType": 11},
{"Channel2": 0, "Ratio2": 37, "EffectType": 11},
{"Channel2": 0, "Ratio2": 41, "EffectType": 11},
{"Channel2": 0, "Ratio2": 45, "EffectType": 11},
{"Channel2": 0, "Ratio2": 49, "EffectType": 11},
{"Channel2": 0, "Ratio2": 53, "EffectType": 11},
{"Channel2": 0, "Ratio2": 57, "EffectType": 11},
{"Channel2": 0, "Ratio2": 61, "EffectType": 11},
{"Channel2": 0, "Ratio2": 66, "EffectType": 11},
{"Channel2": 0, "Ratio2": 70, "EffectType": 11},
{"Channel2": 0, "Ratio2": 74, "EffectType": 11},
{"Channel2": 0, "Ratio2": 78, "EffectType": 11},
{"Channel2": 0, "Ratio2": 82, "EffectType": 11},
{"Channel2": 0, "Ratio2": 86, "EffectType": 11},
{"Channel2": 0, "Ratio2": 90, "EffectType": 11},
{"Channel2": 0, "Ratio2": 94, "EffectType": 11},
{"Channel2": 0, "Ratio2": 98, "EffectType": 11},
{"Channel2": 0, "Ratio2": 102, "EffectType": 11},
{"Channel2": 0, "Ratio2": 107, "EffectType": 11},
{"Channel2": 0, "Ratio2": 111, "EffectType": 11},
{"Channel2": 0, "Ratio2": 115, "EffectType": 11},
{"Channel2": 0, "Ratio2": 119, "EffectType": 11},
{"Channel2": 0, "Ratio2": 123, "EffectType": 11},
{"Channel2": 0, "Ratio2": 127, "EffectType": 11},
{"Channel2": 0, "Ratio2": 127, "EffectType": 11}
]
}
</pre>

The file defines 32 effects. <code>EffectType = 11</code> selects <code>MixS</code>; <code>Channel2 = 0</code> reduces saturation, and <code>Ratio2</code> controls how much. The last effect uses 127, applying the full change.

The ASM code is:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/DecreaseSaturation.paleffect"

; 1 = include the palette in the effect; 0 = exclude it.
!P0 = 1
!P1 = 1
!P2 = 1
!P3 = 1
!P4 = 1
!P5 = 1
!P6 = 1
!P7 = 1

!P8 = 1
!P9 = 1
!PA = 1
!PB = 1
!PC = 1
!PD = 1
!PE = 1
!PF = 1

!EnableFixedColor = 1
!EnableColor00 = 0

; Effect applied when entering the level.
!PaletteEffetID = !PaletteEffectIDDecreaseSaturation31

; Calculated masks: no manual changes needed.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!PaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL
</pre>

'''What you can customize'''

* <code>!P0</code> through <code>!PF</code>: affected palettes.
* <code>!EnableFixedColor</code> and <code>!EnableColor00</code>: whether these colors are affected.
* <code>!PaletteEffetID</code>: selected effect. You can use any ID generated from your effects file, not just this example's final effect.

Defines <code>!PaletteEffectIDDecreaseSaturation0</code> through <code>!PaletteEffectIDDecreaseSaturation31</code> are generated from the <code>*.paleffect</code> and written to <code>DXDefines.asm</code>. Names use PascalCase, with spaces, hyphens, and underscores removed and existing capitals preserved.

The effect is selected in <code>init</code>; you do not need to repeat this every frame. To remove it, write 0 to the global effect ID and leave the palettes enabled so the system restores their original colors:

<pre>
REP #$20
LDA #$0000
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
</pre>

=== Cycling through effects ===

This example runs through a sequence of effects and returns to the first. You can configure the speed, first and last IDs, and affected palettes. The settings shown include only palette 0 and the fixed color.

Save the following in <code>DynamicXtreme/Hue.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel1": 1, "Ratio1": 127, "EffectType": 9},
{"Channel1": 2, "Ratio1": 127, "EffectType": 9},
{"Channel1": 3, "Ratio1": 127, "EffectType": 9},
{"Channel1": 4, "Ratio1": 127, "EffectType": 9},
{"Channel1": 5, "Ratio1": 127, "EffectType": 9},
{"Channel1": 6, "Ratio1": 127, "EffectType": 9},
{"Channel1": 7, "Ratio1": 127, "EffectType": 9},
{"Channel1": 8, "Ratio1": 127, "EffectType": 9},
{"Channel1": 9, "Ratio1": 127, "EffectType": 9},
{"Channel1": 10, "Ratio1": 127, "EffectType": 9},
{"Channel1": 11, "Ratio1": 127, "EffectType": 9},
{"Channel1": 12, "Ratio1": 127, "EffectType": 9},
{"Channel1": 13, "Ratio1": 127, "EffectType": 9},
{"Channel1": 14, "Ratio1": 127, "EffectType": 9},
{"Channel1": 15, "Ratio1": 127, "EffectType": 9},
{"Channel1": 16, "Ratio1": 127, "EffectType": 9},
{"Channel1": 17, "Ratio1": 127, "EffectType": 9},
{"Channel1": 18, "Ratio1": 127, "EffectType": 9},
{"Channel1": 19, "Ratio1": 127, "EffectType": 9},
{"Channel1": 20, "Ratio1": 127, "EffectType": 9},
{"Channel1": 21, "Ratio1": 127, "EffectType": 9},
{"Channel1": 22, "Ratio1": 127, "EffectType": 9},
{"Channel1": 23, "Ratio1": 127, "EffectType": 9},
{"Channel1": 24, "Ratio1": 127, "EffectType": 9},
{"Channel1": 25, "Ratio1": 127, "EffectType": 9},
{"Channel1": 26, "Ratio1": 127, "EffectType": 9},
{"Channel1": 27, "Ratio1": 127, "EffectType": 9},
{"Channel1": 28, "Ratio1": 127, "EffectType": 9},
{"Channel1": 29, "Ratio1": 127, "EffectType": 9},
{"Channel1": 30, "Ratio1": 127, "EffectType": 9},
{"Channel1": 31, "Ratio1": 127, "EffectType": 9},
{"Channel1": 31, "Ratio1": 127, "EffectType": 9}
]
}
</pre>

The file defines 32 hue effects. <code>EffectType = 9</code> selects <code>MixH</code>, and <code>Ratio1 = 127</code> fully applies the selected hue.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/Hue.paleffect"

; 1 = include the palette in the effect; 0 = exclude it.
!P0 = 1
!P1 = 0
!P2 = 0
!P3 = 0
!P4 = 0
!P5 = 0
!P6 = 0
!P7 = 0

!P8 = 0
!P9 = 0
!PA = 0
!PB = 0
!PC = 0
!PD = 0
!PE = 0
!PF = 0

!EnableFixedColor = 1
!EnableColor00 = 0

; Allowed values: $00, $01, $03, $07, $0F, $1F, $3F, $7F, and $FF.
!Delay = $03

!StartingPaletteEffetID = !PaletteEffectIDHue0
!EndPaletteEffetID = !PaletteEffectIDHue31

; Calculated masks: no manual changes needed.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!StartingPaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL

main:
LDA $14
AND #!Delay
BNE .Return

REP #$20
LDA.l DX_Dynamic_Palettes_GlobalEffectID
CMP #!EndPaletteEffetID
BCS .Restart
INC A
BRA .Store
.Restart
LDA #!StartingPaletteEffetID
.Store
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
.Return
RTL
</pre>

'''What you can customize'''

* <code>!P0</code> through <code>!PF</code>, <code>!EnableFixedColor</code>, and <code>!EnableColor00</code>: affected colors.
* <code>!Delay</code>: interval between changes. <code>$00</code> changes every frame, <code>$01</code> every two frames, <code>$03</code> every four, and <code>$07</code> every eight. Use only the values listed in the comment.
* <code>!StartingPaletteEffetID</code> and <code>!EndPaletteEffetID</code>: first and last effects in the cycle. They must form a consecutive ID range, with the start less than or equal to the end.

The cycle displays the last ID before returning to the first. It uses <code>$14</code> to time changes, so the first interval depends on that counter's value when entering the level. To stop it while the action is frozen, also check <code>$9D</code> and <code>$13D4|!addr</code> at the start of <code>main</code>.

Defines <code>!PaletteEffectIDHue0</code> through <code>!PaletteEffectIDHue31</code> are generated from the <code>*.paleffect</code> and written to <code>DXDefines.asm</code>. Names are normalized to PascalCase by removing separators; here, <code>Hue</code> stays unchanged.

=== Running a transition that stops when complete ===

This example advances from the first effect to the last and keeps the final result. You can configure the affected palettes, fixed color, speed, and ID range.

Save the following in <code>DynamicXtreme/Night.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel1": 0, "Channel2": 0, "Ratio1": 0, "Ratio2": 0, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 4, "Ratio2": 4, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 8, "Ratio2": 8, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 12, "Ratio2": 12, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 16, "Ratio2": 16, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 20, "Ratio2": 20, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 25, "Ratio2": 25, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 29, "Ratio2": 29, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 33, "Ratio2": 33, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 37, "Ratio2": 37, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 41, "Ratio2": 41, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 45, "Ratio2": 45, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 49, "Ratio2": 49, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 53, "Ratio2": 53, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 57, "Ratio2": 57, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 61, "Ratio2": 61, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 66, "Ratio2": 66, "EffectType": 2}
]
}
</pre>

The transition has 17 steps. <code>EffectType = 2</code> selects <code>MixRG</code>: it reduces red and green without changing blue. Ratios increase from 0 to 66 to darken the colors gradually without completely removing red and green.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/Night.paleffect"

; 1 = include the palette in the effect; 0 = exclude it.
!P0 = 1
!P1 = 1
!P2 = 1
!P3 = 1
!P4 = 1
!P5 = 1
!P6 = 1
!P7 = 1

!P8 = 1
!P9 = 1
!PA = 1
!PB = 1
!PC = 1
!PD = 1
!PE = 1
!PF = 1

!EnableFixedColor = 1
!EnableColor00 = 0

; Allowed values: $00, $01, $03, $07, $0F, $1F, $3F, $7F, and $FF.
!Delay = $03

!StartingPaletteEffetID = !PaletteEffectIDNight0
!EndPaletteEffetID = !PaletteEffectIDNight16

; Calculated masks: no manual changes needed.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!StartingPaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL

main:
LDA $14
AND #!Delay
BNE .Return

REP #$20
LDA.l DX_Dynamic_Palettes_GlobalEffectID
CMP #!EndPaletteEffetID
BCS .Finished
INC A
STA.l DX_Dynamic_Palettes_GlobalEffectID
.Finished
SEP #$20
.Return
RTL
</pre>

'''What you can customize'''

* <code>!P0</code> through <code>!PF</code>, <code>!EnableFixedColor</code>, and <code>!EnableColor00</code>: affected colors.
* <code>!Delay</code>: interval between changes, using the same allowed values as the cycle example.
* <code>!StartingPaletteEffetID</code> and <code>!EndPaletteEffetID</code>: first and last effects. IDs must be consecutive and in ascending order.

Defines <code>!PaletteEffectIDNight0</code> through <code>!PaletteEffectIDNight16</code> are generated from <code>Night.paleffect</code> and written to <code>DXDefines.asm</code>. Names use PascalCase with separators removed; here, <code>Night</code> stays unchanged.

This example moves between mixing effects. To transition toward another complete palette, use <code>PalTransitionRGB</code> or <code>PalTransitionHSL</code>, described in [[Dynamic_Xtreme_files_and_formats#Palette_transitions|Files and formats]].

Dynamic Xtreme sprite creation guide

2026-10-25T21:56:50Z

Anonimzwx: Created page with "{{Select Language|Dynamic_Xtreme_sprite_creation_guide}} This article explains how to create dynamic sprites using Dynamic Xtreme and PIXI. The guide covers the complete process: preparing graphics, defining poses, including the necessary files in the sprite, and using the system to load and draw its poses on screen. For questions about a call's registers, parameters, or return values, see the ASM API. The relevant sections of this guide lin..."

{{Select Language|Dynamic_Xtreme_sprite_creation_guide}}

This article explains how to create dynamic sprites using Dynamic Xtreme and PIXI.

The guide covers the complete process: preparing graphics, defining poses, including the necessary files in the sprite, and using the system to load and draw its poses on screen.

For questions about a call's registers, parameters, or return values, see the [[Dynamic_Xtreme_ASM_API|ASM API]]. The relevant sections of this guide link directly to the corresponding calls.

== Requirements ==

To follow this guide, you need:

* [https://www.smwcentral.net/?p=section&s=tools&f%5Bname%5D=PIXI PIXI] installed and configured to insert sprites into your ROM.
* Dynamic Xtreme installed and configured. If you have not done this yet, see the [[Dynamic_Xtreme_Quick_Start|Quick Start guide]].

== Files used by a dynamic sprite ==

In addition to the files normally used by PIXI, a dynamic sprite needs:

* '''Graphics file (*.bin):''' the graphics for the sprite's poses.
* '''DynamicInfo (*.dynamicinfo):''' specifies which graphics the sprite uses and how they are divided into poses.
* '''DrawInfo (*.drawinfo):''' the information needed to draw the poses.
* '''ASM file (*.asm):''' the sprite's code, which uses the resources above.

One possible arrangement is to keep the Dynamic Xtreme files with the PIXI resource itself. For example, a normal sprite could use this structure:

<pre>
PIXI/
└── sprites/
└── MySprite/
├── MySprite.asm
├── MySprite.json
└── DynamicXtreme/
├── MySprite.bin
├── MySprite.dynamicinfo
└── MySprite.drawinfo
</pre>

Keep the ASM and configuration file in the sprite's main folder. Store the graphics, DynamicInfo, and DrawInfo in the <code>DynamicXtreme</code> subfolder.

In this arrangement, the sprite's main ASM must include DynamicInfo and DrawInfo with these directives:

<pre>
;#incdyn "DynamicXtreme/MySprite.dynamicinfo"
;#incdri "DynamicXtreme/MySprite.drawinfo"
</pre>

Paths are relative to the ASM containing the directives. For a cluster sprite, extended sprite, or another type supported by PIXI, the whole resource folder can be arranged the same way inside the corresponding PIXI folder.

You can also use Dynamic Xtreme's traditional folders. Put <code>*.dynamicinfo</code> in <code>DynamicInfos</code>, <code>*.drawinfo</code> in <code>DrawInfos</code>, and <code>*.bin</code> graphics in <code>DynamicResources</code>. Dynamic Xtreme discovers files stored this way directly, so the sprite does not need <code>;#incdyn</code> or <code>;#incdri</code> directives.

The first option makes it easier to distribute the sprite with all its resources in one folder; the second retains Dynamic Xtreme's traditional organization. For each format's structure and rules, see [[Dynamic_Xtreme_files_and_formats|Dynamic Xtreme files and formats]].

During installation, Dynamic Xtreme generates the defines used by the sprite code and saves them in <code>DXDefines.asm</code>. This table summarizes the names used in the guide:

{| class="wikitable"
! Example define !! Source !! Purpose
|-
| <code>!RenderBoxXDistanceOutOfScreenMySprite</code>
| Horizontal bounds of the poses in <code>MySprite.drawinfo</code>.
| Configure the horizontal RenderBox distance in INIT.
|-
| <code>!RenderBoxYDistanceOutOfScreenMySprite</code>
| Vertical bounds of the poses in <code>MySprite.drawinfo</code>.
| Configure the vertical RenderBox distance in INIT.
|-
| <code>!MySpritePaletteTableOffset</code>
| The <code>Palettes</code> list in <code>MySprite.dynamicinfo</code>.
| Tell palette assignment which table to use.
|-
| <code>!DynamicPoseIDMySprite000</code>
| The first pose in <code>MySprite.bin</code>, declared under <code>PosesGraphics</code> in DynamicInfo.
| Request that pose's graphics through <code>!Upload</code>. The <code>000</code> suffix identifies the graphics file's first pose; <code>003</code> identifies its fourth.
|-
| <code>!PoseIDMySprite_Frame0</code>
| The <code>Frame0</code> pose declared in <code>MySprite.drawinfo</code>.
| Select the pose drawn by <code>!DXDraw</code>.
|-
| <code>!PaletteEffectIDMyEffect0</code>
| The first effect in <code>MyEffect.paleffect</code>.
| Select the palette effect to apply.
|}

Names are normalized by removing separators and capitalizing each word's first letter: for example, <code>my_sprite</code> becomes <code>MySprite</code>. Always check the exact generated names in <code>DXDefines.asm</code>; the guide also repeats their origin beside each use.

== Sprite structure ==

A dynamic sprite retains the usual PIXI sprite structure, but must prepare Dynamic Xtreme's variables and organize its main routine according to whether it is within drawing distance of the screen.

The structure used in this guide has these parts:

* '''INIT:''' initializes the sprite variables and Dynamic Xtreme state.
* '''Short routine:''' runs the logic that must continue even when the sprite is outside drawing distance.
* '''Long routine:''' handles work needed only within drawing distance, such as requesting and drawing the pose.

=== Include the sprite type defines ===

Before the sprite's code, include the defines file for its resource type:

* <code>NormalSpriteDefines.asm</code> for normal sprites.
* <code>ClusterSpriteDefines.asm</code> for cluster sprites.
* <code>ExtendedSpriteDefines.asm</code> for extended sprites.

For example, if a normal sprite's ASM is in a subfolder of <code>sprites</code>, the include can be written as:

<pre>
incsrc "../NormalSpriteDefines.asm"
</pre>

The path is always relative to the sprite ASM, so adjust it to the resource's folder structure. This file supplies table and routine aliases for the sprite type. Names such as <code>!PoseIndex</code>, <code>!RenderBox</code>, and <code>!Upload</code> therefore select the correct implementation for a normal, cluster, or extended sprite.

=== INIT ===

For normal sprites, <code>INIT</code> must set the <code>RenderBox</code> distances, assign initial values, and invalidate any previous state left in the same PIXI slot.

The following normal sprite example starts at pose 0 and obtains its version and initial flip from the PIXI configuration:

<pre>
print "INIT ",pc
LDA.b #!RenderBoxXDistanceOutOfScreenMySprite
STA !RenderXDistanceOutOfScreen,x
LDA.b #!RenderBoxYDistanceOutOfScreenMySprite
STA !RenderYDistanceOutOfScreen,x

LDA !ExtraBits,x
AND #$04
LSR
LSR
STA !GlobalFlip,x

LDA !ExtraByte1,x
AND #$0F
STA !Version,x

LDA #$00
STA !PoseIndex,x
STA !LocalFlip,x
STA !LastFlip,x

LDA #$FF
STA !Palette,x
STA !LastPoseIndex,x
STA !LastPoseHashIndex,x
STA !LastVersion,x

RTL
</pre>

Each variable in the example has a specific role:

* <code>!RenderXDistanceOutOfScreen</code> and <code>!RenderYDistanceOutOfScreen</code> store the distances used by <code>!RenderBox</code> to decide whether the sprite is still close enough to the screen to draw. <code>!RenderBoxXDistanceOutOfScreenMySprite</code> and <code>!RenderBoxYDistanceOutOfScreenMySprite</code> are generated from DrawInfo and available in <code>DXDefines.asm</code>. The resource name is normalized by removing separators such as spaces and underscores and capitalizing each word's first letter. For example, <code>my_sprite</code> and <code>my sprite</code> become <code>MySprite</code>.
* <code>!PoseIndex</code> selects the desired dynamic pose within DynamicInfo. Zero selects the resource's first pose. An animation routine can assign another value before requesting graphics.
* <code>!Version</code> identifies the sprite's current variant. A version can change its palette, graphics, or behavior. Normal sprites commonly take it from the low four bits of <code>!ExtraByte1,x</code>, allowing up to 16 versions to be selected in Lunar Magic.
* <code>!GlobalFlip</code> is the sprite's overall flip. Normal sprites can obtain it from the extra bit: 0 keeps the original orientation and 1 applies the initial flip. <code>!LocalFlip</code> adds a flip for the current pose. Dynamic Xtreme combines both and stores the effective drawing flip in <code>!LastFlip</code>.
* <code>!Palette</code> stores the currently assigned palette. It starts at <code>$FF</code> because no valid palette has been assigned yet.
* <code>!LastPoseIndex</code> stores the last pose Dynamic Xtreme successfully obtained, and <code>!LastPoseHashIndex</code> stores its VRAM cache slot. Both start at <code>$FF</code> because no pose is available yet.
* <code>!LastVersion</code> stores the version previously processed by palette management. Starting it at <code>$FF</code> ensures the first version is processed even when <code>!Version</code> starts at 0.

If a sprite uses several DrawInfo files, the distances must cover all its graphics. Check each DrawInfo's generated values in <code>DXDefines.asm</code> and use the largest horizontal and vertical distances. For example, if the head and body use separate DrawInfo files, using only the head's distances may stop drawing the sprite while part of its body is still on screen.

Values marked <code>$FF</code> represent invalid states. Besides indicating that no palette or pose is available yet, they prevent reuse of data left by a sprite that previously occupied the same PIXI slot.

==== Initializing cluster and extended sprites ====

Cluster and extended sprites have no dedicated <code>INIT</code> routine. To initialize them once, reserve one of their tables, such as <code>!ClusterMiscTable1</code> or <code>!ExtendedMiscTable1</code>, and give it a name such as <code>!Started</code>:

<pre>
!Started = !ClusterMiscTable1
</pre>

When creating the sprite, set <code>!Started</code> to 0 using the new cluster or extended sprite's index. The slot may have been used before and could still hold another sprite's value.

At the start of <code>SpriteCode</code>, before <code>!RenderBox</code>, check this variable:

<pre>
SpriteCode:
LDA !Started,x
BNE +
JSR Start
RTS
+
!RenderBox
; Rest of the sprite code
</pre>

<code>Start</code> contains the initialization normally done in a normal sprite's <code>INIT</code>. At the end, it sets <code>!Started</code> to 1 so it does not run again on later frames:

<pre>
Start:
; Initialize the sprite here

LDA #$01
STA !Started,x
RTS
</pre>

Because <code>Start</code> is called with <code>JSR</code>, it must end with <code>RTS</code>. The code creating the cluster or extended sprite must also prepare inherited data, such as <code>!PaletteOption</code>, <code>!PaletteAssignmentOption</code>, or <code>!GlobalFlip</code>.

==== PaletteOption ====

<code>!PaletteOption</code> controls the requested palette and whether it receives the global palette effect. Its format is:

<pre>
EPPP----
</pre>

* <code>E</code> determines whether the palette receives the global effect: 0 excludes it and 1 enables it.
* <code>PPP</code> represents a palette from 8 to F: <code>000</code> selects palette 8 and <code>111</code> selects palette F.
* The low four bits are not part of <code>PaletteOption</code>.

With automatic assignment, <code>PPP = 000</code> searches all eight palettes for a free slot; a nonzero <code>0XX</code> value limits the search to palettes 8–B, and <code>1XX</code> limits it to C–F. With manual assignment, <code>PPP</code> directly selects the palette.

For normal sprites, <code>!PaletteOption</code> directly uses <code>!ExtraByte1,x</code>. The remaining four bits commonly select the sprite version, giving the whole byte this format:

<pre>
EPPPVVVV
</pre>

* <code>EPPP</code> contains the palette options described above.
* <code>VVVV</code> selects one of 16 sprite versions, from 0 to 15.

<code>!PaletteOption</code> directly uses the high four bits, while <code>INIT</code> copies the low four bits to <code>!Version</code>. You do not need to copy <code>PaletteOption</code> into another table.

==== PaletteAssignmentOption ====

<code>!PaletteAssignmentOption</code> determines how the sprite's palette is assigned:

<pre>
--AA----
</pre>

* <code>AA = 00</code>: '''automatic assignment'''. Dynamic Xtreme finds a slot allowed by <code>PaletteOption</code> and loads the palette dynamically.
* <code>AA = 01</code>: '''manual assignment'''. <code>PaletteOption</code> specifies the exact slot, and Dynamic Xtreme loads the palette dynamically.
* <code>AA = 10</code>: '''manual assignment without upload'''. The sprite uses the palette already in the level; Dynamic Xtreme does not load a new one.

For normal sprites, <code>!PaletteAssignmentOption</code> directly uses <code>!ExtraProp2,x</code>. Set the mode through bits 5 and 4 of Extra Property Byte 2; it does not need to be copied into another table in <code>INIT</code>.

For cluster and extended sprites, set <code>!PaletteOption</code> and <code>!PaletteAssignmentOption</code> manually when they are created. Normally, copy the creating sprite's assignment mode. When copying <code>PaletteOption</code>, clear the low four bits because they contain a normal sprite's version, not palette options.

If the spawned sprite uses the same palette as its parent, copy its <code>PaletteOption</code> after clearing the low four bits. If it uses a different palette and the parent uses automatic assignment, keep the same search range. For manual assignment, with or without upload, add <code>$10</code> to the masked value to select the next palette.

In the last case, the parent cannot use palette F because the spawned sprite needs the next palette. Configure the parent with a palette from 8 to E.

Besides these variables, <code>INIT</code> can initialize any tables needed for the sprite's behavior.

=== SpriteCode ===

See [[Dynamic_Xtreme_ASM_API#RenderBox|RenderBox]] in the API for its inputs and result.

<code>SpriteCode</code> starts with <code>!RenderBox</code>. It returns carry set when the sprite is within drawing distance and clear when it is outside. This selects the short or long routine.

A basic structure is:

<pre>
SpriteCode:
!RenderBox
BCS .LongRoutine

.ShortRoutine
LDA #$00
%SubOffScreen()
; Put your sprite's logic here
RTS

.LongRoutine
JSR PaletteManagement
BCC ..Return

JSR PoseManagement
BCC ..Return

JSR Draw
; Put your sprite's logic here
..Return
RTS
</pre>

==== Short routine ====

The short routine runs when the sprite is outside the area checked by <code>!RenderBox</code>. Run only the core logic needed to maintain its behavior, without requesting dynamic graphics, processing its palette, or drawing it. The exact contents depend on the sprite and may include movement, state, timers, interactions, or animation.

For normal sprites, calling <code>%SubOffScreen()</code> here is recommended. It takes a value from 0 to 7 in A to select the offscreen removal setting; the example uses the usual value, 0. This lets PIXI remove the sprite when it gets far enough offscreen, without running this check in the more expensive drawing path.

==== Long routine ====

The long routine runs when the sprite is within drawing distance. It handles the complete process: palette management, requesting the dynamic pose or updating its last-use record if it is already in VRAM to protect it from replacement, drawing the sprite, and finally running the same core logic as the short routine.

There is no need to call <code>%SubOffScreen()</code> again in the long routine. <code>!RenderBox</code> has already determined that the sprite is within drawing distance, so the check would be redundant.

<code>PaletteManagement</code> and <code>PoseManagement</code> return carry set when a usable resource exists. If either returns carry clear, the example branches to <code>..Return</code> and ends the routine. The sprite is not drawn and the subsequent logic is not run during that frame.

The following sections develop the palette, pose, and drawing routines. Their names are just one way to organize the code and can be changed to suit the sprite.

== Palette management ==

=== Load a dynamic palette ===

See [[Dynamic_Xtreme_ASM_API#PaletteAssignment|PaletteAssignment]] in the API for details.

To use palette assignment in a normal sprite, configure at least one Extra Byte in its <code>*.cfg</code> or <code>*.json</code>:

* '''Extra Byte 1:''' supplies <code>!PaletteOption</code>; in this guide's example, its low four bits select <code>!Version</code>.
* '''Extra Property Byte 2:''' sets <code>!PaletteAssignmentOption</code> through bits 5 and 4: <code>00</code> for automatic assignment, <code>01</code> for manual assignment, and <code>10</code> for manual assignment without upload. These bits correspond to <code>$00</code>, <code>$10</code>, and <code>$20</code>; the remaining bits can serve other sprite options.

Load a dynamic palette through <code>!PaletteAssignment</code>. Simply load the resource's generated palette table offset into 16-bit A:

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignment
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> is generated from the palettes declared in DynamicInfo and appears in <code>DXDefines.asm</code>. The DynamicInfo name is normalized by removing spaces, underscores, and other separators and capitalizing each word's first letter. For example, <code>my_sprite.dynamicinfo</code> produces <code>MySprite</code>.

<code>!PaletteAssignment</code> uses <code>!Version</code> to select a table entry: version 0 uses the first palette, version 1 the second, and so on. It also uses <code>!PaletteOption</code> and <code>!PaletteAssignmentOption</code> to decide where and how to assign it.

The routine returns carry set when a usable palette exists and clear when one could not yet be obtained. <code>SpriteCode</code> therefore checks carry before loading poses and drawing. Call <code>!PaletteAssignment</code> every frame of the long routine to keep the assignment while the sprite uses it.

=== Select a palette without changing the sprite version ===

A sprite's palette can change without changing its version or behavior. For example, it can switch between its normal palette and a second palette during an animation or temporary state. Keeping both palettes as separate resources also lets other sprites reuse the second one.

Because <code>!PaletteAssignment</code> selects its entry using <code>!Version</code>, temporarily save the sprite's logical version, set the desired palette index, and restore the original version afterward:

<pre>
PaletteManagement:
LDA !Version,x
PHA

LDA #$02
STA !Version,x

REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignment

PLA
STA !Version,x
RTS
</pre>

Here, <code>!PaletteAssignment</code> uses table entry 2, but the sprite's behavior keeps its original version. This separates palette selection from the character's logical variant. <code>PLA</code> and <code>STA</code> do not change carry, so <code>PaletteManagement</code> still returns the correct <code>!PaletteAssignment</code> result.

<code>!MySpritePaletteTableOffset</code> is generated from DynamicInfo and stored in <code>DXDefines.asm</code>. The same name normalization applies: remove separators and capitalize each word's first letter, so <code>my_sprite</code> becomes <code>MySprite</code>.

=== Concatenate a local effect with the global effect ===

See the API entries for [[Dynamic_Xtreme_ASM_API#PaletteAssignmentNoUpload|PaletteAssignmentNoUpload]], [[Dynamic_Xtreme_ASM_API#ConcatenateRGBPaletteEffectToGlobal|ConcatenateRGBPaletteEffectToGlobal]], and [[Dynamic_Xtreme_ASM_API#ConcatenateHSLPaletteEffectToGlobal|ConcatenateHSLPaletteEffectToGlobal]].

When a palette needs its own effect combined with the global palette effect, use <code>!PaletteAssignmentNoUpload</code> followed by <code>!ConcatenateRGBPaletteEffectToGlobal</code> or <code>!ConcatenateHSLPaletteEffectToGlobal</code>:

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

PHY

LDA !Palette,x
TAX

LDA $14
AND #$06
TAY

REP #$20
LDA PaletteEffects,y

PLY
!ConcatenateRGBPaletteEffectToGlobal

.Return
RTS

PaletteEffects:
dw !PaletteEffectIDMyEffect0
dw !PaletteEffectIDMyEffect1
dw !PaletteEffectIDMyEffect2
dw !PaletteEffectIDMyEffect3
</pre>

<code>!PaletteAssignmentNoUpload</code> assigns the palette and prepares its base address without performing the final upload. It also leaves information in Y that tells the concatenation routine whether the effect must be rebuilt.

This example uses <code>$14</code>, Super Mario World's main frame counter, to select one of four effects. Since Y is temporarily needed to read <code>PaletteEffects</code>, it is first saved with <code>PHY</code> and restored with <code>PLY</code>. Pass that restored value unchanged to the concatenation routine.

Before concatenation, X must contain <code>!Palette</code>, which already represents the index required by the routine. A must contain the 16-bit local effect ID. Here, Y indexes a table to load the ID, but the ID is ultimately passed in A.

<code>!MySpritePaletteTableOffset</code> comes from DynamicInfo and is stored in <code>DXDefines.asm</code>. The <code>!PaletteEffectIDMyEffectX</code> defines are generated from a <code>*.paleffect</code> during installation and stored in the same file. In both cases, names are normalized by removing spaces, underscores, and other separators and capitalizing each word's first letter. For example, <code>my_effect.paleffect</code> produces <code>MyEffect</code>; <code>X</code> is the effect index within the collection.

Use <code>!ConcatenateRGBPaletteEffectToGlobal</code> for RGB effects such as <code>PaletteTransitionRGB</code>, and <code>!ConcatenateHSLPaletteEffectToGlobal</code> for HSL effects such as <code>MixH</code>. To combine local and global effects, enable bit <code>E</code> of <code>PaletteOption</code>. The routine handles any conversions needed when the two effects use different color spaces. See [[Dynamic_Xtreme_files_and_formats#Effect_types|Effect types]] for each effect's color space.

Concatenation returns carry set when a usable result exists, including a previous result kept as a fallback, and clear when that palette has no valid result yet. Preserve this carry so <code>SpriteCode</code> can decide whether to continue drawing.

== Dynamic pose management ==

Request dynamic poses with <code>!Upload</code> or <code>!UploadWithoutPoseOffset</code>. These routines search the VRAM cache and request a load if the pose is not available. Call them every frame of the long routine to keep the sprite's pose in use.

=== Upload ===

See [[Dynamic_Xtreme_ASM_API#Upload|Upload]] in the API for details.

<code>!Upload</code> takes the resource's base dynamic ID in 16-bit A and adds <code>!PoseIndex</code>:

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
!Upload
RTS
</pre>

Here, <code>!PoseIndex = 0</code> requests the first pose, 1 the next, and so on. This lets the animation routine change only <code>!PoseIndex</code> while <code>PoseManagement</code> keeps the same base ID.

<code>!DynamicPoseIDMySprite000</code> is generated from DynamicInfo during installation and appears in <code>DXDefines.asm</code>. Names are normalized by removing spaces, underscores, and other separators and capitalizing each word's first letter. For example, <code>my_sprite.dynamicinfo</code> produces <code>MySprite</code>.

<code>!Upload</code> returns carry set when a usable pose exists. This can be the pose requested this frame or the sprite's last valid pose, used as a fallback while the new one cannot yet be loaded. Carry is clear only when the sprite has no usable pose.

When a request succeeds, <code>!LastPoseIndex</code> stores the available pose and <code>!LastPoseHashIndex</code> its VRAM cache entry. Drawing must therefore use the last available pose's state rather than assume <code>!PoseIndex</code> has been loaded.

=== UploadWithoutPoseOffset ===

See [[Dynamic_Xtreme_ASM_API#UploadWithoutPoseOffset|UploadWithoutPoseOffset]] in the API for details.

<code>!UploadWithoutPoseOffset</code> also takes a dynamic ID in 16-bit A but uses it directly, without adding <code>!PoseIndex</code>:

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite003
!UploadWithoutPoseOffset
RTS
</pre>

Use this variant when your code has already selected the exact dynamic ID, for example through a table or condition. Carry has the same meaning as in <code>!Upload</code>: set when a usable pose exists, clear when none is available.

<code>!DynamicPoseIDMySprite003</code> is also generated from DynamicInfo and stored in <code>DXDefines.asm</code>. The same CamelCase-style normalization removes separators and capitalizes each word's first letter.

Currently, the normal and cluster sprite defines publish <code>!UploadWithoutPoseOffset</code>. Extended sprites must use <code>!Upload</code> with <code>!PoseIndex</code> until their defines file publishes this alias.

<code>!DynamicPoseID...</code> defines belong to dynamic loading. Do not confuse them with DrawInfo's <code>!PoseID...</code> defines, which are used to draw the pose.

== Drawing poses on screen ==

Once <code>PoseManagement</code> obtains a usable pose, draw it with <code>!DXDraw</code> or <code>!DXDrawWithOffset</code>. Both use the sprite position, flip, palette, and dynamic pose state kept by Dynamic Xtreme.

Before either call, prepare:

* The drawing pose ID in 16-bit A.
* Additional properties in <code>!PropParam</code>, using the <code>YXCC----</code> format.
* The highest allowed tile priority in <code>!MaxTilePriorityParam</code>.

<code>!MaxTilePriorityParam</code> accepts:

* <code>$00</code>: maximum priority.
* <code>$01</code>: high priority.
* <code>$02</code>: the sprite type's own priority.
* <code>$03</code>: lowest priority.

=== DXDraw ===

See [[Dynamic_Xtreme_ASM_API#DXDraw|DXDraw]] in the API for details.

<code>!DXDraw</code> draws the pose using the sprite's normal position as its origin. A basic drawing routine is:

<pre>
Draw:
LDA #$20
STA !PropParam

LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDraw
RTS
</pre>

<code>!LastPoseIndex</code> is added to the first drawing ID to select the pose actually available. Use <code>!LastPoseIndex</code>, not <code>!PoseIndex</code>: while a new pose is unavailable, Dynamic Xtreme may keep the previous pose as a fallback.

This example assumes DrawInfo poses follow the same order as DynamicInfo poses. If they differ, convert <code>!LastPoseIndex</code> to the matching drawing ID, for example using a table.

<code>!PoseIDMySprite_Frame0</code> is generated from DrawInfo during installation and appears in <code>DXDefines.asm</code>. Generated names remove spaces, underscores, and other separators and capitalize each word's first letter. For example, <code>my_sprite</code> produces <code>MySprite</code>.

<code>!PoseID...</code> identifies a drawing pose declared in DrawInfo. Do not confuse it with DynamicInfo's <code>!DynamicPoseID...</code>, used by <code>!Upload</code> to request dynamic graphics.

<code>!DXDraw</code> combines <code>!PropParam</code> with <code>!LastFlip</code>, the assigned palette, and the pose's own properties. It also uses <code>!LastPoseHashIndex</code> to locate graphics in the VRAM cache. If this is <code>$FF</code>, nothing is drawn.

=== DXDrawWithOffset ===

See [[Dynamic_Xtreme_ASM_API#DXDrawWithOffset|DXDrawWithOffset]] in the API for details.

<code>!DXDrawWithOffset</code> works the same way but shifts the drawing relative to the sprite. Supply signed 8-bit offsets in <code>!XOffsetParam</code> and <code>!YOffsetParam</code>:

<pre>
Draw:
LDA #$08
STA !XOffsetParam

LDA #$F8
STA !YOffsetParam

LDA #$20
STA !PropParam

LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDrawWithOffset
RTS
</pre>

This example shifts the drawing 8 pixels right and 8 pixels up. Positive X moves right and negative X left; positive Y moves down and negative Y up.

The offset changes only where the pose is drawn, not the sprite's actual position, hitbox, or interactions. It is useful for aligning graphics, adding visual movement, or drawing several parts of an entity from one logical position.

As above, <code>!PoseIDMySprite_Frame0</code> is generated from DrawInfo and stored in <code>DXDefines.asm</code>. Dynamic Xtreme's name normalization removes separators such as spaces and underscores and capitalizes each word's first letter.

=== DrawStatic ===

See [[Dynamic_Xtreme_ASM_API#DrawStatic|DrawStatic]] in the API for details.

Dynamic Xtreme can also draw static poses. Declare them with <code>.IsStatic</code> in DrawInfo and draw them with <code>%DrawStatic()</code>. Their graphics are already in VRAM, so they do not need <code>!Upload</code>, <code>!LastPoseIndex</code>, or <code>!LastPoseHashIndex</code>.

When a static pose uses the default tile (0) for all components, drawing takes the tile number from <code>!Tile</code>, which represents scratch RAM <code>$05</code>. This lets the same pose, such as a one-tile pose, draw different graphics. Prepare this value before calling <code>%DrawStatic()</code>:

<pre>
LDA #$80 ; Tile number to draw
STA !Tile ; Scratch RAM $05
</pre>

Prepare this value for every drawing call that needs it. Setting it only in INIT is insufficient because other routines share the scratch RAM.

For dynamic poses, <code>!DXDraw</code> and <code>!DXDrawWithOffset</code> obtain the tile from the graphics' VRAM cache location, so <code>!Tile</code> does not need to be set manually. If a static DrawInfo declares nondefault tiles, drawing uses those values directly.

This example draws a static pose at a normal sprite's position, without flipping and using palette A:

<pre>
Draw:
LDA #$20
STA !PropParam

LDA #$02
STA !MaxTilePriorityParam

REP #$21
LDA #!PoseIDMyStaticSprite_Frame0
%DrawStatic(0, 1, #$00, #$04, "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

The first parameter selects additional offsets: 0 draws at the supplied position; 1 also applies <code>!XOffsetParam</code> and <code>!YOffsetParam</code>. The remaining parameters provide the drawing context, flip, palette, and 16-bit X/Y positions. Quote indexed positions so the comma in <code>,x</code> is not treated as a macro argument separator.

<code>%DrawStatic()</code> ends the routine with <code>RTS</code>, so this example does not add another <code>RTS</code> after the macro.

Here, <code>#$00</code> disables flipping and <code>#$04</code> selects palette A. These arguments can also use tables or variables when the sprite needs to change orientation or palette.

<code>!PoseIDMyStaticSprite_Frame0</code> is generated from DrawInfo during installation and appears in <code>DXDefines.asm</code>. Its name uses PascalCase: remove spaces, underscores, hyphens, and other separators and capitalize each word's first letter.

For more on declaring static poses, see [[Dynamic_Xtreme_files_and_formats|Dynamic Xtreme files and formats]].

== Install and test the sprite ==

Whenever a resource processed by Dynamic Xtreme changes, reinstall Dynamic Xtreme first and then reinsert the sprites with PIXI. This includes <code>*.dynamicinfo</code>, <code>*.drawinfo</code>, <code>*.bin</code> graphics, <code>*.paleffect</code> effects, and any other dynamic resource used by the sprite.

Order matters: Dynamic Xtreme must process the resources and regenerate their data and defines before PIXI assembles the sprite with the updated information.

If you add, remove, or modify <code>;#incdyn</code>, <code>;#incdri</code>, or <code>;#incpale</code> resource includes in the ASM, reinstall Dynamic Xtreme first and then PIXI.

If you only modify the sprite's <code>*.asm</code> code without changing those includes, you do not need to reinstall Dynamic Xtreme. Run PIXI again.

For the complete resource installation, configuration, and reinstallation process, see the [[Dynamic_Xtreme_Quick_Start|Dynamic Xtreme Quick Start guide]].

After each installation, test the sprite in-game and check its poses, palettes, flipping, and offsets throughout its states and animations.

== Common mistakes ==

=== Using an unnormalized name in a generated define ===

Names inside Dynamic Xtreme's generated defines must follow the tool's normalization: remove spaces, underscores, and hyphens and capitalize each word's first letter, using PascalCase.

For example, a pose named <code>my_sprite-pose</code> uses <code>MySpritePose</code> in a define such as:

<pre>
!DynamicPoseIDMySpritePose
</pre>

Using the original separators, different capitalization, or confusing <code>!DynamicPoseID...</code> with <code>!PoseID...</code> prevents Asar from finding the symbol. When unsure, check the exact generated name in <code>DXDefines.asm</code>.

=== Incorrectly initializing sprite variables ===

Initialize Dynamic Xtreme's variables to valid values whenever a sprite is created. With <code>!PaletteAssignment</code>, <code>!Palette</code>, <code>!LastPoseIndex</code>, <code>!LastPoseHashIndex</code>, and <code>!LastVersion</code> must start at <code>$FF</code>; <code>!PoseIndex</code>, <code>!LocalFlip</code>, and <code>!LastFlip</code> normally start at 0. Also configure the <code>!RenderBox</code> distances.

Incorrect initialization may reuse a palette, pose, or data left by another sprite in the same slot. Cluster and extended sprites must initialize through the simulated startup routine explained above.

=== Not reserving an Extra Byte for the palette ===

A normal sprite that loads palettes needs at least one Extra Byte in its <code>*.cfg</code> or <code>*.json</code>. Dynamic Xtreme uses <code>Extra Byte 1</code> as <code>!PaletteOption</code> and commonly uses its low four bits for <code>!Version</code>.

Without any declared Extra Bytes, <code>!ExtraByte1,x</code> will not contain the configuration needed to select the sprite's palette and version correctly.

=== Not restoring a fixed palette in the short routine ===

A sprite can use a fixed palette already loaded in the level instead of calling <code>!PaletteAssignment</code>. Even then, assign the desired drawing palette manually to <code>!Palette,x</code>.

Values increase by two and select sprite palettes 8–F:

* <code>$00</code>: palette 8.
* <code>$02</code>: palette 9.
* <code>$04</code>: palette A.
* <code>$06</code>: palette B.
* <code>$08</code>: palette C.
* <code>$0A</code>: palette D.
* <code>$0C</code>: palette E.
* <code>$0E</code>: palette F.

Assign the value in <code>INIT</code> and in the short routine. When <code>!RenderBox</code> selects the short routine, it invalidates <code>!Palette,x</code>, so restore the fixed palette there:

<pre>
; Inside INIT
LDA #$04 ; Palette A
STA !Palette,x

; Inside SpriteCode
.ShortRoutine
LDA #$04 ; Palette A
STA !Palette,x

LDA #$00
%SubOffScreen()
; Put your sprite's logic here
RTS
</pre>

This manual assignment is only for sprites using fixed palettes without <code>!PaletteAssignment</code>. Sprites with dynamic palette loading must retain the assignment flow explained in the palette management section.

Dynamic Xtreme files and formats

2026-10-25T21:56:15Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_files_and_formats}}

Dynamic Xtreme uses a set of dedicated file formats to give you control over the resources, effects, and data used during gameplay.

This page documents the file types handled by the tool, their purpose, how they work, and their specific formats, including both current and legacy formats. Understanding this structure helps you make full use of Dynamic Xtreme.

Many of Dynamic Xtreme's legacy formats originated in Dynamic X, the earlier version from which the project evolved. They remain fully compatible to support the many existing resources developed for Dynamic X.

The main file types and their formats are described below.

== File types ==

Dynamic Xtreme uses several specialized file types:

* '''Dynamic resources:''' resources stored uncompressed in the ROM. Commonly used for dynamic sprites, graphics changes, tilemap changes, or palette changes.
* '''Palette Effects (*.paleffect):''' files used to register palette effects.
* '''Dynamic Info (*.dynamicinfo):''' files used to insert dynamic resources into the ROM and generate the data required by dynamic sprites.
* '''Draw Info (*.drawinfo):''' files used to generate sprite poses (animation frames) so they can be drawn on screen.

== Including files from PIXI and UberASMTool ==

PIXI and UberASMTool resources can declare the files they use through special comments in their main ASM file:

<pre>
;#incdyn "ruta/al/recurso.dynamicinfo"
;#incdri "ruta/al/recurso.drawinfo"
;#incpale "ruta/al/recurso.paleffect"
</pre>

Each directive registers a different file type:

* <code>;#incdyn</code> includes a <code>*.dynamicinfo</code> file.
* <code>;#incdri</code> includes a <code>*.drawinfo</code> file.
* <code>;#incpale</code> includes a <code>*.paleffect</code> file.

Paths are relative to the main ASM containing the directive. Included files can be in the same folder or any of its subfolders.

Dynamic Xtreme searches for these directives only in the main ASM files registered in PIXI's and UberASMTool's lists. It does not follow files loaded through <code>incsrc</code>.

Resources referenced inside a <code>*.dynamicinfo</code> or
<code>*.paleffect</code> included this way use the
definition file's folder as their base directory.

== Dynamic resources ==

Dynamic resources are one of Dynamic Xtreme's core systems. They are stored uncompressed in the ROM so they can be loaded and used quickly during gameplay.

=== How does the system work? ===

Dynamic Xtreme gathers all dynamic resources, organizes them into packages of at most one bank (32 or 64 KB), and automatically inserts them into the ROM. If high banks are available, the tool prioritizes them for insertion to improve space organization.

There is no strict restriction on the type of data that can be inserted, although most files are '''*.bin''' files.

=== Common uses ===

Dynamic resources are commonly used for:
* '''Graphics:''' dynamic sprite graphics or real-time graphics replacement.
* '''Tilemaps:''' replacing tiles in the level's different layers.
* '''Palettes:''' replacing complete palettes or assigning specific palettes to dynamic sprites.
* '''Other data:''' anything you want to store in the ROM, such as .brr audio samples, data tables, and so on.

This makes the system flexible enough for graphics and any other data that needs to be readily available in the ROM.

=== Palette files ===

Currently, the recommended way to save palettes is as binary files ('''*.bin'''), with each color taking 2 bytes in the SNES color format. Tools such as [https://www.smwcentral.net/?p=section&a=details&id=24827 Pal2Bin] can help with this.

The SNES uses the BGR555 color format: each color uses 5 bits for blue, 5 for green, and 5 for red.

Conceptually, the bits are arranged as follows:

<code>-BBBBB GGGGG RRRRR</code>

However, because of the SNES byte order, the bytes are stored in reverse order in memory, producing this arrangement:

<code>GGG RRRRR -BBBBB GG</code>

Because this format can be confusing for users unfamiliar with SNES hardware, improved support for '''*.pal''' files is planned. This format is more familiar and widely used in modern graphics tools.

Palettes used by dynamic sprites must contain no more than 15 colors. Include only colors 1 through 15 of the corresponding palette, since color 0 is transparent.

=== Dynamic sprite graphics ===

A dynamic sprite's graphics are divided into poses. Each pose contains the tiles that must be loaded into VRAM to display one animation frame.

Dynamic Xtreme supports two ways to organize these graphics:

* The '''current format''', recommended for new resources.
* The '''legacy format''', retained for compatibility with
resources made for Dynamic X.

Both formats produce the same result in the game. The only difference is how the graphics must be organized in the file.

==== Current format ====

In the current format, graphics are organized into 16×16-pixel spaces.

Each pose's tiles are placed consecutively. The next pose's graphics begin immediately after the previous pose's.

The author chooses the tile order within each pose in the graphics file. DynamicInfo specifies how many tiles belong to each pose, and DrawInfo specifies where each tile is drawn. Both must match the graphics layout.

For example, a 32×32-pixel pose normally uses four 16×16 tiles:

[[File:imagen 2026-05-17 221817296.png|thumb]]

The number of tiles used by each pose is declared in the
<code>*.dynamicinfo</code> file through
<code>NumberOf16x16TilesPerPose</code>.

Dynamic Xtreme automatically rearranges these graphics into the internal format used for DMA transfers. The resource author therefore does not need to prepare the VRAM layout manually.

This is the recommended format for new resources.

If the final 16×16 tile is only partially used, specify which parts to keep with <code>q</code>, <code>h</code>, or <code>q3</code>. Prepare the graphics in a complete 16×16 space; Dynamic Xtreme keeps the indicated parts and discards the rest when processing the resource.

Each cell in the following tables represents an 8×8 tile. The entire table represents the pose's final 16×16 tile. Green marks used parts and gray marks discarded parts.

===== q =====

{| class="wikitable"
! !! Left half !! Right half
|-
! Top half
| style="background-color:#d5f5dc; color:#202122;" | Top-left 8×8 tile: used
| style="background-color:#eaecf0; color:#202122;" | Top-right 8×8 tile: unused
|-
! Bottom half
| style="background-color:#eaecf0; color:#202122;" | Bottom-left 8×8 tile: unused
| style="background-color:#eaecf0; color:#202122;" | Bottom-right 8×8 tile: unused
|}

===== h =====

{| class="wikitable"
! !! Left half !! Right half
|-
! Top half
| style="background-color:#d5f5dc; color:#202122;" | Top-left 8×8 tile: used
| style="background-color:#d5f5dc; color:#202122;" | Top-right 8×8 tile: used
|-
! Bottom half
| style="background-color:#eaecf0; color:#202122;" | Bottom-left 8×8 tile: unused
| style="background-color:#eaecf0; color:#202122;" | Bottom-right 8×8 tile: unused
|}

===== q3 =====

{| class="wikitable"
! !! Left half !! Right half
|-
! Top half
| style="background-color:#d5f5dc; color:#202122;" | Top-left 8×8 tile: used
| style="background-color:#d5f5dc; color:#202122;" | Top-right 8×8 tile: used
|-
! Bottom half
| style="background-color:#d5f5dc; color:#202122;" | Bottom-left 8×8 tile: used
| style="background-color:#eaecf0; color:#202122;" | Bottom-right 8×8 tile: unused
|}

==== Legacy format ====

The legacy format requires the graphics to already be organized into the blocks that DMA will transfer.

For a pose using seven or fewer 16×16 tiles, split each tile into two 16×8 halves. Store all top halves first, followed by all bottom halves.

For example, a pose made of four tiles:

<code>t1 t2 t3 t4</code>

must be stored like this:

<code>t1th t2th t3th t4th t1bh t2bh t3bh t4bh</code>

Where:

* <code>th</code> means the tile's top half.
* <code>bh</code> means the tile's bottom half.

When a pose contains eight or more 16×16 tiles, each full row of eight tiles can be stored directly. Arrange the remaining tiles using the half-tile system described above.

Each pose's layout is declared through
<code>PosesChunksSizes</code> in the
<code>*.dynamicinfo</code>.

This format provides direct control over the internal layout but is harder to prepare and maintain. It is mainly recommended for older resources or advanced use cases.

== Palette effects ==

Palette effect files are stored in the PaletteEffects folder and use the '''*.paleffect''' extension.

Palette effects modify the colors used by the game in real time. Dynamic Xtreme's global palette effect system can use these effects.

The global effect affects every color in each palette enabled to receive it. Likewise, an effect applied to a whole sprite affects its entire palette. These systems do not select individual colors within a palette.

To apply an effect only to specific colors, do it manually using the macros and routines described in the [[Dynamic_Xtreme_ASM_API|Dynamic Xtreme ASM API]].

Internally, these systems modify the palette colors' '''RGB''' or '''HSL''' channels to produce different visual effects.

Common uses include:

* Day-to-night transitions.
* Red flashes to signal danger.
* Blinking cyan effects for objects about to explode.
* Shifting tints for disco-style effects.
* Smooth transitions between visual states.
* Lighting or atmosphere effects.

The system supports many combinations and effects.

=== Effect types ===

The following effects are available:
<ul>
<li>'''MixRGB (ID 0)''': interpolates the '''RGB''' channels toward a base color.</li>
<li>'''MixHSL (ID 1)''': interpolates the '''HSL''' channels toward a base color.</li>
<li>'''MixRG (ID 2)''': interpolates only '''R''' and '''G'''.</li>
<li>'''MixHS (ID 3)''': interpolates only '''H''' and '''S'''.</li>
<li>'''MixRB (ID 4)''': interpolates only '''R''' and '''B'''.</li>
<li>'''MixHL (ID 5)''': interpolates only '''H''' and '''L'''.</li>
<li>'''MixGB (ID 6)''': interpolates only '''G''' and '''B'''.</li>
<li>'''MixSL (ID 7)''': interpolates only '''S''' and '''L'''.</li>
<li>'''MixR (ID 8)''': interpolates only the '''R''' channel.</li>
<li>'''MixH (ID 9)''': interpolates only the '''H''' channel.</li>
<li>'''MixG (ID 10)''': interpolates only the '''G''' channel.</li>
<li>'''MixS (ID 11)''': interpolates only the '''S''' channel.</li>
<li>'''MixB (ID 12)''': interpolates only the '''B''' channel.</li>
<li>'''MixL (ID 13)''': interpolates only the '''L''' channel.</li>
<li>'''PalTransitionRGB (ID 14)''': interpolates an entire palette toward another using '''RGB''' channels.</li>
<li>'''PalTransitionHSL (ID 15)''': interpolates an entire palette toward another using '''HSL''' channels.</li>
<li>'''PalFunctionRGB (ID 16)''': applies a linear transformation to the '''RGB''' channels:

* R = R11*R + R12*G + R13*B
* G = R21*R + R22*G + R23*B
* B = R31*R + R32*G + R33*B

Where:

* RXY are ratios.
* R is the red channel.
* G is the green channel.
* B is the blue channel.

'''Note:''' this effect is not implemented yet.
</li>

<li>'''PalFunctionHSL (ID 17)''': applies a linear transformation to the '''HSL''' channels:

* H = R11*H + R12*S + R13*L
* S = R21*H + R22*S + R23*L
* L = R31*H + R32*S + R33*L

Where:

* '''RXY''' are ratios.
* '''H''' is hue.
* '''S''' is saturation.
* '''L''' is lightness.

'''Note:''' this effect is not implemented yet.
</li>
</ul>

==== File format ====

Palette effects use a JSON-based format:

<pre>
{
"Effects": []
}
</pre>

Where:

* '''Effects''': the list of effects used.

===== Simple format =====

The simple format defines a single effect:

<pre>
{
"Channel1": 31,
"Channel2": 0,
"Channel3": 0,
"Ratio1": 64,
"Ratio2": 64,
"Ratio3": 64,
"EffectType": 0
}
</pre>

Where:

<ul>
<li>'''Channel1''', '''Channel2''', and '''Channel3''' contain the main channel values
<ul>
<li>For '''RGB''' effects:
<ul>
<li>1 = R</li> <li>2 = G</li> <li>3 = B</li>
</ul>
<li>For '''HSL''' effects:
<ul>
<li>1 = H</li> <li>2 = S</li> <li>3 = L</li>
</ul>
</ul>
</li>
<li>'''Ratio1''', '''Ratio2''', and '''Ratio3''' are interpolation factors used to calculate how strongly the effect influences each channel. Values range from 0 (minimum influence) to 127 (maximum influence).</li>
<li>'''EffectType''' is the ID of the effect used.</li>
</ul>

For example, the <code>MixRGB</code> above blends the original colors toward red: <code>Channel1 = 31</code>, <code>Channel2 = 0</code>, and <code>Channel3 = 0</code>. With all three ratios set to 64, the result is approximately halfway between each original color and that red. A black color therefore becomes a medium-intensity red. Increasing the ratios brings the result closer to the specified red.

===== Palette transitions =====

The <code>PalTransitionRGB</code> and
<code>PalTransitionHSL</code> effects interpolate colors from one
palette toward another.

Unlike regular blending effects, these use the <code>Palette</code> field to specify the target palette:

<pre>
{
"Palette": "Palettes/NightPalette.bin",
"Ratio1": 64,
"Ratio2": 64,
"Ratio3": 64,
"EffectType": 14
}
</pre>

This example uses <code>PalTransitionRGB</code>, whose ID is
<code>14</code>. For an HSL transition, use
<code>PalTransitionHSL</code>, whose ID is <code>15</code>.

The file specified in <code>Palette</code> must contain 2-byte BGR555 colors. Dynamic Xtreme automatically converts the palette into the internal format required by the RGB or HSL effect.

<code>Ratio1</code>, <code>Ratio2</code>, and
<code>Ratio3</code> control interpolation for their respective
channels and must range from 0 to 127.

When the <code>*.paleffect</code> is in the traditional <code>PaletteEffects</code> folder, the
<code>Palette</code> path is resolved relative to
<code>DynamicResources</code>.

When the effect is included from PIXI or UberASMTool through
<code>;#incpale</code>, its path is resolved relative to the folder
containing the <code>*.paleffect</code> file.

==== Value ranges ====

* Channel values ('''Channel''') range from '''0''' to '''31'''.
* Ratio values ('''Ratio''') range from '''0''' to '''127'''.

== DynamicInfo ==

'''DynamicInfo''' files are stored in the '''DynamicInfos''' folder and use the '''*.dynamicinfo''' extension.

These files have two main purposes:

* Insert dynamic resources into the ROM.
* Specify which graphics belong to dynamic sprites and how each pose must be loaded.

The basic structure of a DynamicInfo file is:

<pre>
PosesGraphics:
MyGraphics.bin
AnotherGraphics.bin

Palettes:
MyPal.bin
AnotherPal.bin

Resources:
MyResource.bin
AnotherResource.bin
</pre>

These sections are lists of dynamic resources to be included by Dynamic Xtreme.

The base directory for paths depends on how the DynamicInfo file is registered:

{| class="wikitable"
! Method !! Base directory for PosesGraphics, Palettes, and Resources files
|-
| Traditional folders: DynamicInfo inside <code>DynamicInfos</code>
| Paths are relative to <code>DynamicResources</code>, next to the Dynamic Xtreme executable.
|-
| Included through <code>;#incdyn</code>
| Paths are relative to the folder containing the included <code>*.dynamicinfo</code> file.
|}

For example, with the traditional method, <code>Graficos/MyGraphics.bin</code> is found at <code>DynamicResources/Graficos/MyGraphics.bin</code>, not beside the DynamicInfo.

* '''PosesGraphics''' contains dynamic sprite graphics files. These must use the '''*.bin''' format.
* '''Palettes''' contains palette files. These currently use the '''*.bin''' format, with '''*.pal''' support planned for the future.
* '''Resources''' includes arbitrary dynamic resources without a specific format restriction.

When multiple files are listed under PosesGraphics, they are combined internally into one large graphics block in declaration order.

Each pose is then cut from that combined data and stored in the ROM in the arrangement best suited to the dynamic system.

As a result, there is no significant practical difference between:

* Using one large graphics file.
* Using several separate smaller files.

Both approaches produce the same internal result in Dynamic Xtreme.

In addition to these resource lists, '''DynamicInfo''' files define the dynamic poses used by the sprite.

How those poses are defined depends on the resource's format:

* Current format ('''NumberOf16x16TilesPerPose''').
* Legacy format ('''PosesChunksSizes''').

=== Current format ===

The current format was designed to simplify creating and maintaining dynamic sprites.

You only need to specify how many 16×16 tiles each pose uses. Dynamic Xtreme processes the graphics and converts them to the optimized format used internally by the dynamic system.

Example:

<pre>
NumberOf16x16TilesPerPose:
.Pose0 5
.Pose1 7h
.Pose2..6 4
</pre>

In this example:

* Pose0 uses five 16×16 tiles.
* Pose1 uses seven 16×16 tiles plus a top half (16×8).
* Pose2 through Pose6 use four 16×16 tiles each.

Modifiers can represent partial tiles:

* '''q''': top-left 8×8 tile.
* '''h''': top half (16×8).
* '''q3''': top half plus bottom-left tile (16×8 + 8×8).

This allows a 16×16 tile to contain only part of its graphics. Partial tiles do not support every possible combination, because many would be impractical for the system. Only the most common, useful arrangements are supported.

Internally, Dynamic Xtreme automatically converts this format to the legacy format, which is optimized for more efficient DMA transfers to VRAM.

=== Legacy format ===

The legacy format uses a table named PosesChunksSizes to specify the internal dynamic graphics layout manually.

Example:

<pre>
PosesChunksSizes:
Pose0_PoseChunksSizes:
db $02,$02
Pose1_PoseChunksSizes:
db $02,$02
</pre>

Each pose has a subtable containing two values.

These values represent how many DMA operations would be needed to transfer the pose's graphics into VRAM under ideal conditions: assuming the sprite is aligned to the start of the sprite VRAM area. Under those conditions, one or two DMA operations are needed.

Usually, the first DMA operation transfers more data than the second.

Each value specifies the number of 8×8 tiles transferred by that DMA operation.

For example:

<pre>
db $02,$02
</pre>

means:

* The first DMA operation transfers two 8×8 tiles.
* The second transfers another two 8×8 tiles.

In special cases where the sprite uses enough 16×16 tiles to fill exact VRAM rows, such as multiples of eight 16×16 tiles, the entire transfer can use a single DMA operation. In those cases, set the second value to $00.

The current format replaced this format because most users found it complex and unintuitive. NumberOf16x16TilesPerPose is now recommended, although the legacy format remains fully compatible and offers more flexibility for advanced cases.

== DrawInfo ==

DrawInfo files are stored in DrawInfos with the '''*.drawinfo''' extension. They contain the information needed to draw poses on screen.

Dynamic Xtreme collects this information and automatically generates optimized graphics routines. Each routine groups poses with similar characteristics and is optimized specifically for that kind of pose. This provides a shared pose drawing system that is efficient in a wide range of situations.

Understanding DrawInfo files requires a basic understanding of SNES OAM.

OAM is memory used to store sprite information. SMW uses 8×8 and 16×16 tiles.

Each tile has the following attributes:

<ul>
<li>'''TileCode''': sometimes simply called Tile, this is the internal ID the console uses to select a particular graphic in VRAM.
<br/>
'''Note:''' for dynamic sprites, define TileCodes as if the sprite were loaded at the start of the sprite VRAM area.
<br/>
Dynamic Xtreme automatically adjusts these values based on where the pose is actually loaded in VRAM during gameplay.
</li>
<li>'''Properties''': a byte containing the tile's properties, using this format:
* '''YXCCPPPT'''
Where:
<ul>
<li>'''Y''': whether the tile is vertically flipped.</li>
<li>'''X''': whether the tile is horizontally flipped.</li>
<li>'''CC''': tile priority relative to layers (higher value = higher priority).</li>
<li>'''PPP''': sprite palette (000 => palette 8, 001 => palette 9, ..., 111 => palette F).</li>
<li>'''T''': graphics page (0 => SP12, 1 => SP34).</li>
</ul>

'''Note:''' common Properties can be set for all tiles in a pose or sprite. The most important DrawInfo properties are therefore usually Y, X, and T, while CC and PPP are commonly set by the calling code.

For dynamic sprites, T normally does not need to be set manually: Dynamic Xtreme detects the pose's graphics page and sets this bit automatically.</li>
<li>'''Size''': tile size:
<ul>
<li>$00: small tile (8×8).</li>
<li>$02: large tile (16×16).</li>
</ul>
</li>
</ul>

Each tile also has:

* X displacement (X Offset)
* Y displacement (Y Offset)

These values move the tile relative to the sprite's base position.

Dynamic Xtreme supports two DrawInfo formats: current and legacy.

=== Current format ===

The current DrawInfo format was designed to make drawing files much easier to read and maintain.

Unlike the legacy format, it supports:

* Grouping multiple poses.
* Grouping tile ranges.
* Using individual default values.
* Omitting unnecessary subtables.
* Defining individual values or complete value lists.

Example:

<pre>
MyPose_Pose0..4:
.NumberOfTiles: 5
.TileCode2: $02
.TileCode3..4: $04
.Properties: $00,$40,$00,$00,$40
.XOffsets: $00,$10,$F8,$08,$18
.XPivot: $08
.YOffset2..4: $10
.YPivot: $10
.Size0..4: $02
</pre>

In this example:

* '''MyPose_Pose0..4''': shared information for poses 0 through 4 with the name "MyPose".
* '''.NumberOfTiles''': each pose uses five tiles.
* '''.TileCode2''': changes only tile 2's '''TileCode'''.
* '''.TileCode3..4''': changes the '''TileCode''' for tiles 3 and 4.
* '''.Properties''': an individual '''Properties''' value for every tile.
* '''.XOffsets''': an individual '''XOffset''' for every tile.
* '''.YOffset2..4''': changes '''YOffset''' only for tiles 2 through 4.
* '''.Size0..4''': sets the size of tiles 0 through 4.

Tiles are numbered from 0. For example, <code>.NumberOfTiles: 5</code> provides tiles 0 through 4.

Singular directives change one tile or a specified range of tiles.

Examples:

<pre>
.TileCode2: $02
.TileCode3..4: $04
.YOffset1..3: $10
</pre>

In these cases:

* '''.TileCode2:''': changes only tile 2.
* '''.TileCode3..4''': changes only tiles 3 and 4.
* '''.YOffset1..3''': changes YOffset for tiles 1 through 3.

Plural directives explicitly define a complete value list for every tile in the pose.

Examples:

<pre>
.Properties: $00,$40,$00,$00,$40
.XOffsets: $00,$10,$F8,$08,$18
</pre>

In these cases:

* '''.Properties''': a complete Properties list.
* '''.XOffsets''': a complete XOffsets list.

This allows simple general settings to be combined with specific changes only where needed.

Declarations are applied in the order they appear. If several change the same tile attribute, the last value wins. For example, after <code>.Properties: $00,$40,$00,$00,$40</code>, write <code>.Property2: $80</code> to change only tile 2's property to <code>$80</code>. If you write the complete list afterward, that list replaces the previous values for all tiles.

When a value is not explicitly defined, Dynamic Xtreme uses these defaults:

* '''TileCode''': $00
* '''Property''': $00
* '''XOffset''': $00
* '''YOffset''': $00
* '''Size''': $02

Unlike the legacy format, these defaults work individually per tile, letting you omit only the unnecessary information without affecting the rest of the pose.

Offsets specify each tile's position relative to the sprite, in pixels. Without flipping, <code>XOffset</code> is added to the sprite's X position and <code>YOffset</code> to its Y position. For example, an <code>XOffset</code> of <code>$10</code> puts the tile 16 pixels to the right; <code>$F8</code> represents −8 and puts it 8 pixels to the left.

'''XPivot''' and '''YPivot''' calculate where tiles should be placed when the whole pose is flipped horizontally or vertically. They reflect the layout rather than rotating the pose.

For horizontal flipping, the calculation follows these steps:

# Start with the sprite's X position.
# Add <code>XPivot</code>.
# Subtract the tile's original <code>XOffset</code> to reverse its displacement.
# For a 16×16 tile, subtract another 8 pixels to adjust for its size. An 8×8 tile needs no such adjustment.

The flipped tile's X position is therefore:

* '''8×8 tile:''' <code>sprite X + XPivot − XOffset</code>.
* '''16×16 tile:''' <code>sprite X + XPivot − XOffset − 8</code>.

For example, a pose has two 16×16 tiles with <code>XOffset</code> values of 0 and 16. Setting <code>.XPivot: $18</code> (24 decimal) swaps their positions when the pose is flipped:

{| class="wikitable"
! Tile !! Unflipped !! Horizontally flipped
|-
| First: XOffset = 0
| Sprite X + 0
| Sprite X + 24 − 0 − 8 = Sprite X + 16
|-
| Second: XOffset = 16
| Sprite X + 16
| Sprite X + 24 − 16 − 8 = Sprite X + 0
|}

Vertical flipping uses the same calculation with the sprite's Y position, <code>YPivot</code>, and <code>YOffset</code>.

These flipped offsets are calculated during installation. During gameplay, the drawing routine uses the offsets for the requested flip.

If '''XPivot''' is omitted, the pose does not support horizontal flipping. Likewise, omitting '''YPivot''' disables vertical flipping for that pose.

This lets Dynamic Xtreme generate more optimized graphics routines when those features are unnecessary, while slightly reducing ROM usage.

You can also use:

<pre>
.IsStatic
</pre>

This marks the defined poses as static rather than dynamic. All poses are dynamic by default.

The legacy DrawInfo format remains fully compatible. The current format primarily makes DrawInfo files easier to write, read, and maintain while retaining flexibility.

=== Legacy format ===

Legacy DrawInfo uses separate tables to define each pose tile attribute.

This format follows the structure commonly used in hand-written SNES graphics routines. It was intended to give sprite authors familiar with that approach a recognizable, intuitive layout for DrawInfo.

Example:

<pre>
Dynamic:
true

Tiles:
MyPose0_Tiles:
db $00
MyPose1_Tiles:
db $00

Properties:
MyPose0_Properties:
db $00
MyPose1_Properties:
db $00

XDisplacements:
MyPose0_XDisp:
db $00
MyPose1_XDisp:
db $00
MyPose0_XDispFlip:
db $00
MyPose1_XDispFlip:
db $00

YDisplacements:
MyPose0_YDisp:
db $01
MyPose1_YDisp:
db $01
MyPose0_YDispFlip:
db $FF
MyPose1_YDispFlip:
db $FF

Sizes:
MyPose0_Sizes:
db $02
MyPose1_Sizes:
db $02
</pre>

In this format:

* Each attribute has its own section.
* Each pose requires a separate subtable.
* Every value must be written manually.
* There are no tile ranges or pose groups.

The main tables are:

* '''Tiles''': TileCodes.
* '''Properties''': OAM properties.
* '''XDisplacements''': horizontal offsets.
* '''YDisplacements''': vertical offsets.
* '''Sizes''': tile sizes (8×8 or 16×16).

XDisplacements and YDisplacements can also have flipped versions:

* XDispFlip
* YDispFlip

These tables let you specify the offsets used for horizontal or vertical flipping manually.

The directive:

<pre>
Dynamic: true
</pre>

marks the poses as dynamic. Set it to false to mark them as static.

As in the current format, default values are automatic. When a table is absent, Dynamic Xtreme uses:

* '''TileCode''': $00
* '''Property''': $00
* '''XOffset''': $00
* '''YOffset''': $00
* '''Size''': $02

This format remains fully compatible with Dynamic Xtreme, although the current format is recommended because it is considerably easier to read, maintain, and edit.

Dynamic Xtreme Quick Start

2026-10-25T21:55:41Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_Quick_Start}}

This guide explains how to perform a basic Dynamic Xtreme installation on Windows or Linux.

If this is your first time using the tool, follow the steps in order. You do not need to understand the system's internals to install it.

== Requirements ==

Dynamic Xtreme requires the .NET 8 runtime. Download and install the version for your operating system from Microsoft's official website:

[https://dotnet.microsoft.com/download/dotnet/8.0 .NET 8 Runtime]

The tool supports Windows and Linux. You only need the .NET runtime, not the full SDK.

You can download Dynamic Xtreme from SNEStorage: [https://snestorage.dev/Resource/7 SNEStorage - Dynamic Xtreme]

== Prepare your resources ==

Before running Dynamic Xtreme, add all the resources you want to install to your project.

=== Resources for PIXI and UberASMTool ===

Current resources usually include their
<code>*.asm</code> or <code>*.json</code> file along with the files they
need. Copy the entire package without changing its folder structure.

In PIXI, use the folder for the sprite type:

* <code>sprites</code> for normal sprites.
* <code>cluster</code> for cluster sprites.
* <code>extended</code> for extended sprites.
* For other types, use the folder specified by the resource.

In UberASMTool, use the folder for the code type:

* <code>level</code> for level code.
* <code>overworld</code> for overworld code.
* <code>gamemode</code> for game mode code.
* For other types, use the folder specified by the resource.

After copying the resource, add it to PIXI's or UberASMTool's list file as usual.

Resources prepared for Dynamic Xtreme already contain the necessary declarations in their main ASM file. Keep the ASM, JSON, and supplied folders together to preserve their relative paths.

=== Traditional folders ===

Some resources use Dynamic Xtreme's traditional folders. In that case, use this arrangement:

These folders are next to the Dynamic Xtreme executable: <code>dxt.exe</code> on Windows or <code>dxt</code> on Linux.

{| class="wikitable"
! File type
! Folder
|-
| <code>*.dynamicinfo</code>
| <code>DynamicInfos</code>
|-
| <code>*.drawinfo</code>
| <code>DrawInfos</code>
|-
| <code>*.paleffect</code>
| <code>PaletteEffects</code>
|-
| Graphics, palettes, and other related files
| <code>DynamicResources</code>
|}

Always use the method specified by the resource. Do not move a modern sprite's or UberASM resource's files into the traditional folders unless its instructions tell you to.

== Full installation ==

=== Run the tool ===

Run Dynamic Xtreme from its own folder.

* On Windows, double-click <code>dxt.exe</code>.
* On Linux, open a terminal in the Dynamic Xtreme folder and run:

<pre>
./dxt
</pre>

The tool will ask a series of questions to configure the installation.

=== Configure paths ===

Your paths and selected features are saved in <code>Settings/Settings.json</code> inside the Dynamic Xtreme folder. The tool uses this file to retrieve your configuration for later installations.

You can type each path or drag the corresponding file into the terminal. Then press Enter to continue.

If you leave an answer blank and press Enter, Dynamic Xtreme uses the value saved in <code>Settings/Settings.json</code>. If no value has been saved and the path is optional, that integration is skipped.

Paths are requested in this order:

# '''Input ROM'''
#: Select the Super Mario World ROM you want to modify.

# '''Output ROM'''
#: Enter the path of the ROM that will contain the installation result.

# '''PIXI executable'''
#: Select the PIXI executable. This path allows Dynamic Xtreme's
#: routines and defines to be integrated with PIXI.

# '''UberASMTool executable'''
#: Select the UberASMTool executable if your project uses
#: UberASM code.

# '''GPS executable'''
#: Select the GPS executable if your project uses
#: custom blocks.

# '''PIXI list'''
#: Select the list file where you registered the sprites
#: your project will use.

# '''UberASMTool list'''
#: Select the list file where you registered the UberASM
#: code your project will use.

The PIXI, UberASMTool, and GPS paths and their lists are optional. If you do not use a tool and no path has been saved, leave its answer blank.

To stop using an integration with saved paths, edit <code>Settings/Settings.json</code> and set its values to empty strings (<code>""</code>):

* PIXI: <code>PixiPath</code> and <code>PixiListPath</code>.
* UberASMTool: <code>UberasmToolPath</code> and <code>UberasmListPath</code>.
* GPS: <code>GPSPath</code>.

Do not delete the fields or replace the entire file. You can then leave those paths blank in subsequent prompts without restoring the previous integration.

=== Select features ===

After configuring the paths, Dynamic Xtreme asks which features you want to install.

Answer <code>Y</code> to enable a feature or
<code>N</code> to disable it.

If you press Enter without typing anything, the value saved in <code>Settings/Settings.json</code> is retained. On the first installation, the feature's default value is used.

For a typical installation, you can enable features without warnings. If a red warning appears, read it carefully and check compatibility with your project before enabling that feature.

See [[Dynamic_Xtreme#Features|Features]] for what each option does, and [[Dynamic_Xtreme#Compatibility|Compatibility]] for possible resource conflicts and RAM usage.

=== Typical installation example with PIXI and UberASMTool ===

This example uses PIXI and UberASMTool with the default options. The Windows paths are fictional; replace them with your project's paths. On Linux, provide the paths to the corresponding executables.

{| class="wikitable"
! Prompt !! Example answer
|-
| Input ROM || <code>C:\MiHack\MiHack.smc</code>
|-
| Output ROM || <code>C:\MiHack\MiHack_DX.smc</code>
|-
| PIXI executable || <code>C:\MiHack\PIXI\pixi.exe</code>
|-
| UberASMTool executable || <code>C:\MiHack\UberASMTool\UberASMTool.exe</code>
|-
| GPS executable || Leave blank if unused and no path is saved.
|-
| PIXI list || <code>C:\MiHack\PIXI\list.txt</code>
|-
| UberASMTool list || <code>C:\MiHack\UberASMTool\list.txt</code>
|}

Use these feature settings:

{| class="wikitable"
! Feature !! Enabled !! Answer
|-
| <code>GraphicsChange</code> || Yes || <code>Y</code>
|-
| <code>PalettesChange</code> || Yes || <code>Y</code>
|-
| <code>DynamicPoses</code> || Yes || <code>Y</code>
|-
| <code>DrawingSystem</code> || Yes || <code>Y</code>
|-
| <code>PalettesEffects</code> || Yes || <code>Y</code>
|-
| <code>Free7E2000</code> || Yes || <code>Y</code>
|-
| <code>ControllerOptimization</code> || Yes || <code>Y</code>
|-
| <code>FixedColorOptimization</code> || Yes || <code>Y</code>
|-
| <code>KevinLMVRAMOptimization</code> || No || <code>N</code>
|-
| <code>StatusBarOptimization</code> || No || <code>N</code>
|-
| <code>PlayerFeatures</code> || No || <code>N</code>
|-
| <code>YoshiFeatures</code> || No || <code>N</code>
|}

On SA-1 ROMs, <code>Free7E2000</code> is disabled automatically.

Enter retains the saved value if you have used the tool before. To reproduce this configuration, answer <code>Y</code> or <code>N</code> according to the table; defaults are used only when there is no previous selection.

== Command-line installation ==

After an interactive installation, Dynamic Xtreme saves your selected paths and features in
<code>Settings/Settings.json</code>.

You can reuse this configuration for later installations without answering every question again.

On Windows, open a terminal in the Dynamic Xtreme folder and run:

<pre>
.\dxt.exe -use-settings
</pre>

On Linux, run:

<pre>
./dxt -use-settings
</pre>

If a saved path is no longer valid, Dynamic Xtreme returns to interactive mode to request the configuration.

Available options:

{| class="wikitable"
! Option
! Alias
! Description
|-
| <code>-use-settings</code>
| <code>-us</code>
| Uses the saved paths and features without displaying the
prompts again.
|-
| <code>-verbose</code>
| <code>-v</code>
| Shows more detailed installation information.
|-
| <code>-help</code>
|
| Shows help and the available options.
|-
| <code>-version</code>
|
| Shows the installed Dynamic Xtreme version.
|}

Options can be combined. For example, to use the saved configuration and show detailed information:

'''Windows:'''

<pre>
.\dxt.exe -use-settings -verbose
</pre>

'''Linux:'''

<pre>
./dxt -use-settings -verbose
</pre>

To change paths or selected features, run Dynamic Xtreme without <code>-use-settings</code> and answer the prompts again.

== Finish the installation ==

Interactive and command-line installations produce the same result.

The installation result is saved in <code>log.txt</code> next to the Dynamic Xtreme executable. This file contains all installation details.

Dynamic Xtreme prepares the PIXI, UberASMTool, and GPS integrations but does not run those tools. After installing Dynamic Xtreme, run your project's external tools again on the output ROM.

'''When to reinstall:'''

* If you change graphics, palettes, or <code>*.dynamicinfo</code>, <code>*.drawinfo</code>, or <code>*.paleffect</code> files, reinstall Dynamic Xtreme and then the tools that use those resources.
* If you add, remove, or modify the <code>;#incdyn</code>, <code>;#incdri</code>, or <code>;#incpale</code> resource includes in the ASM, also reinstall Dynamic Xtreme and then the tools that use those resources.
* If you only change the <code>*.asm</code> code without changing those includes, you do not need to reinstall Dynamic Xtreme. Reinsert the code with the appropriate tool.

When Dynamic Xtreme needs to be reinstalled, use this order:

# Run Dynamic Xtreme to regenerate and install its resources.
# Run PIXI, UberASMTool, GPS, and any other
#: tool that uses Dynamic Xtreme's generated data again.

This order matters because resource addresses and IDs may change each time Dynamic Xtreme runs.

Dynamic Xtreme

2026-10-25T21:54:58Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme}}

Dynamic Xtreme is a tool for dynamic graphics and palettes in Super Mario World on the SNES. Built for the ROM hacking community, it lets graphics and colors change in real time during gameplay. Its dynamic graphics system is flexible and modular, with a focus on performance.

A dynamic sprite loads resources, such as graphics or palettes, in real time during gameplay. A static sprite uses resources that were already loaded when the level began.

Dynamic Xtreme does not break the SNES hardware limits: it works within them, optimizing memory use and transfers to reduce their impact and make them much less noticeable during gameplay.

Its main features include:
* Real-time (on-the-fly) graphics and palette changes.
* The most powerful and flexible dynamic sprite system available for Super Mario World.
* An Advanced Drawing System that can draw any registered frame on screen, with full control over priority, layer, offsets, and properties.
* Advanced palette effects, including real-time changes to hue, saturation, brightness, color blending, smooth transitions, and individual RGB and HSL channels.
* Complete replacement of player graphics and palettes, supporting any Mario size, any number of frames, and any animation style.
* Yoshi graphics replacement using a layout like the original game's.
* Extensive NMI handler optimizations to maximize performance.

Dynamic Xtreme's features are selected during installation so a project can use only what it needs. Some have dependencies, compatibility issues, or restrictions on uninstalling them; check each option's warnings. The tool aims to make complex visual effects easier to implement in Super Mario World hacks while maintaining a high level of compatibility and stability.

== Project goals ==

Dynamic Xtreme's main goal is to make dynamic sprites easier to use and provide full support for real-time graphics, palette, and tilemap changes.

The project aims to make the most of the SNES without requiring advanced knowledge of the console's internal hardware. Traditional dynamic systems are often complex and rely heavily on technical concepts such as VRAM, CGRAM, OAM, and DMA. Dynamic Xtreme hides much of that complexity behind more modern, readable tools and formats that are easier to use.

Another main goal is to maintain high performance even in visually complex situations, allowing extensive use of dynamic graphics, palette effects, and advanced drawing systems without unnecessarily compromising performance.

Dynamic Xtreme also aims to make dynamic sprites as natural and straightforward to use as regular sprites. People focused on level design or content creation should be able to work with dynamic resources without constantly worrying about the system's internal technical limitations.

== Features ==

During installation, you can choose which features to enable. The names in parentheses match the installer options and <code>Settings.json</code>.

=== Graphics, poses, and palettes ===

{| class="wikitable"
! Feature !! Purpose
|-
| Graphics changes (<code>GraphicsChange</code>) || Allows graphics to be loaded during gameplay. This is the foundation for tile animations, level graphics changes, and dynamic poses.
|-
| Palette changes (<code>PalettesChange</code>) || Allows palettes to be loaded and managed during gameplay. Includes automatic palette assignment so sprites can share the same colors without loading them multiple times.
|-
| Dynamic poses (<code>DynamicPoses</code>) || Manages VRAM space as a pose cache: reuses loaded poses, shares them between entities, and chooses which ones to replace when more space is needed. This avoids unnecessary loads.
|-
| Pose drawing (<code>DrawingSystem</code>) || Draws both dynamic and static poses defined in DrawInfo files. Allows control over their tiles, position, flipping, palette, and drawing priority.
|-
| Palette effects (<code>PalettesEffects</code>) || Changes colors using RGB and HSL effects: tinting palettes, adjusting hue, saturation, or lightness, and making transitions between palettes. Effects can apply to individual resources or globally.
|}

Dynamic pose loading and drawing are separate systems: you can draw a static pose without loading its graphics dynamically.

=== Player and Yoshi ===

{| class="wikitable"
! Feature !! Purpose
|-
| Player features (<code>PlayerFeatures</code>) || Allows player graphics and palettes to be changed and adapts player drawing and pose loading for custom systems. Also allows the player to be hidden or dynamic uploads to be disabled. May conflict with patches that modify player graphics or palettes; read the installer warning before enabling it.
|-
| Yoshi features (<code>YoshiFeatures</code>) || Allows Yoshi's graphics to be changed while retaining the original pose layout. Requires <code>PlayerFeatures</code> and shares its compatibility restrictions.
|}

=== Memory and optimizations ===

These options reorganize some of the game's work to leave more time for graphics and palette transfers. NMI is the routine that updates the display during the interval between frames.

{| class="wikitable"
! Feature !! Purpose
|-
| Free the <code>$7E2000</code> area (<code>Free7E2000</code>) || On ROMs without SA-1, avoids keeping certain original player, Yoshi, and animation graphics in RAM and reads them from ROM instead. Dynamic Xtreme uses the recovered space for its internal variables; it is not freely available for other uses without reservation. This option does not apply to SA-1 ROMs.
|-
| Controller optimization (<code>ControllerOptimization</code>) || Moves controller processing out of NMI to leave more time for display updates.
|-
| Fixed color optimization (<code>FixedColorOptimization</code>) || Reduces NMI work for updating the fixed color used by the game's color math.
|-
| Kevin's Lunar Magic VRAM optimization (<code>KevinLMVRAMOptimization</code>) || Integrates Kevin's optimization for Lunar Magic VRAM updates and moves some of its processing out of NMI. Use this version instead of installing the original patch separately. Once installed, it must not be uninstalled: doing so can break the ROM.
|-
| Status bar optimization (<code>StatusBarOptimization</code>) || Reduces the original status bar's NMI work. Incompatible with resources that replace or modify it, such as custom status bars or patches that remove it.
|}

For options that may conflict with other resources and the RAM used by the system, see [[#Compatibility|Compatibility]].

Some features depend on others: <code>DynamicPoses</code> requires <code>GraphicsChange</code>; <code>PalettesEffects</code> requires <code>PalettesChange</code>; <code>PlayerFeatures</code> requires both graphics and palette changes; and <code>YoshiFeatures</code> requires <code>PlayerFeatures</code>.

== Quick Start ==

'''Quick installation guide:''' [[Dynamic_Xtreme_Quick_Start|Quick Start]]

== Tools and support ==

Pending

== Files and formats ==

'''Related article:''' [[Dynamic_Xtreme_files_and_formats|Dynamic Xtreme files and formats]]

== Dynamic sprite creation guide ==

To learn how to prepare, program, load, and draw a dynamic sprite, see the [[Dynamic_Xtreme_sprite_creation_guide|Dynamic Xtreme dynamic sprite creation guide]].

== Dynamic Xtreme with UberASM ==

The [[Dynamic_Xtreme_UberASM_guide|Dynamic Xtreme UberASM guide]] shows how to reserve palettes, configure dynamic sprite space and the per-frame data limit, create animations, change player graphics, and apply palette effects.

== API ==

The [[Dynamic_Xtreme_ASM_API|ASM API reference]] explains how to use Dynamic Xtreme's variables, defines, routines, and macros. It covers each call's inputs and results, with examples for poses, drawing, palettes, color effects, and graphics transfers, as well as multiplication and division macros.

== How the system works ==

The article on [[Dynamic_Xtreme_internal_workings|Dynamic Xtreme's internal workings]] explains the organization of NMI and game modes, graphics and palette loading, pose drawing, optimizations, the dynamic pose cache, and palette effects.

== Compatibility ==

In general, features without installer warnings do not usually have compatibility problems with other resources. These are:

* <code>GraphicsChange</code>
* <code>PalettesChange</code>
* <code>DynamicPoses</code>
* <code>DrawingSystem</code>
* <code>PalettesEffects</code>
* <code>Free7E2000</code>
* <code>ControllerOptimization</code>
* <code>FixedColorOptimization</code>

This does not guarantee that every resource combination will work: two pieces of code may still use the same RAM, the same VRAM space, or modify the same game routine. Also, <code>YoshiFeatures</code> requires <code>PlayerFeatures</code>, so the latter's restrictions still apply.

=== Features with compatibility restrictions ===

{| class="wikitable"
! Optional feature !! Possible conflicts and what to do
|-
| <code>PlayerFeatures</code> || May conflict with '''LX5's Powerups''', '''Player 8x8 tiles DMAer''', '''Player 32x32''', and other systems that replace player graphics or palette loading. '''Player Revolution''' is compatible. If your player system needs those original routines, leave this option disabled; you must also disable <code>YoshiFeatures</code>.
|-
| <code>YoshiFeatures</code> || Depends on <code>PlayerFeatures</code> and inherits its compatibility restrictions, even though it has no separate warning. If a resource is incompatible with <code>PlayerFeatures</code>, enabling only <code>YoshiFeatures</code> cannot avoid the conflict: leave both disabled.
|-
| <code>StatusBarOptimization</code> || Incompatible with resources that modify, replace, or remove the original status bar, such as '''LX5's DKC Style Status Bar''', '''Minimalistic Status Bar''', and '''Nuke Status Bar'''. Leave this optimization disabled if you use one of them.
|-
| <code>KevinLMVRAMOptimization</code> || Integrates Kevin's Lunar Magic VRAM optimization patch: use this version instead of installing the original separately. Its warning also states that it '''must not be uninstalled after installation''', because doing so can break the ROM. To revert it, restore a backup made before installation.
|}

These features are optional: leave a conflicting feature disabled and continue using Dynamic Xtreme's other systems, respecting their dependencies. Disabling an option does not undo another patch's changes or remove the uninstall restriction on <code>KevinLMVRAMOptimization</code>.

=== RAM usage ===

The main addresses are configured in <code>ASM/DXDefines.asm</code> inside the Dynamic Xtreme directory. In the repository, this is <code>DynamicXtremeLibrary/ASM/DXDefines.asm</code>.

The space used depends on the enabled features and whether the ROM uses SA-1. The following ranges include both endpoints and were calculated with '''all features that reserve RAM enabled''', <code>!VRAMTransferSize = 64</code>, and <code>!CGRAMTransferSize = 64</code>:

{| class="wikitable"
! Configuration !! <code>!Variables</code> block !! Size !! <code>!Variables2</code> block !! Size
|-
| LoROM with <code>Free7E2000</code> || <code>$7E2000–$7E2500</code> || <code>$0501</code>: 1281 bytes || <code>$7E2800–$7E3608</code> || <code>$0E09</code>: 3593 bytes
|-
| LoROM without <code>Free7E2000</code> || <code>$7FB440–$7FB940</code> || <code>$0501</code>: 1281 bytes || <code>$7F9C80–$7FAA88</code> || <code>$0E09</code>: 3593 bytes
|-
| SA-1 || <code>$40C000–$40C47E</code> || <code>$047F</code>: 1151 bytes || <code>$418AFF–$419907</code> || <code>$0E09</code>: 3593 bytes
|}

The two internal blocks total '''4874 bytes on LoROM''' and '''4744 bytes on SA-1'''. The difference comes from the drawing system's 130 bytes, which are reserved only on LoROM. The gap between the blocks is not automatically occupied.

Disabling a feature removes its conditional reservations and shifts the addresses that follow. Increasing <code>!VRAMTransferSize</code> or <code>!CGRAMTransferSize</code> also increases their table sizes.

==== Sprite tables ====

<code>DX_FreeRams</code> and <code>DX_FreeRams2</code> '''are not available for your own variables''': the sprite tables from <code>DynamicXSpritesTables.asm</code> and <code>MoreSpriteMiscs.asm</code> begin there. You must also reserve them when using those resources.

With the same configuration as the table above, their ranges are:

{| class="wikitable"
! Configuration !! Tables starting at <code>DX_FreeRams</code> !! Size !! Tables starting at <code>DX_FreeRams2</code> !! Size
|-
| LoROM with <code>Free7E2000</code> || <code>$7E2501–$7E26EC</code> || 492 bytes || <code>$7E3609–$7E3824</code> || 540 bytes
|-
| LoROM without <code>Free7E2000</code> || <code>$7FB941–$7FBB2C</code> || 492 bytes || <code>$7FAC82–$7FAE9D</code> || 540 bytes
|-
| SA-1 || <code>$40C47F–$40C6D8</code> || 602 bytes || <code>$419908–$419BCD</code> || 710 bytes
|}

Including these tables, the described space totals '''5906 bytes on LoROM''' and '''6056 bytes on SA-1'''. Tables are calculated for 12 normal sprites on LoROM and 22 on SA-1, plus the corresponding cluster, extended, and smoke slots.

Normally, <code>DX_FreeRams2</code> starts immediately after the second internal block. On LoROM without <code>Free7E2000</code>, it is placed separately using <code>!Variables3 = $7FAC82</code>, so its tables do not immediately follow <code>!Variables2</code>.

Dynamic Xtreme also uses the existing fixed color and palette mirrors: <code>$7E0701</code> (2 bytes) and <code>$7E0703</code> (512 bytes) on LoROM. Their declared SA-1 addresses are <code>$406701</code> and <code>$006703</code>. These are neither additional reservations within the blocks above nor free addresses for your code.

==== Relocating RAM to resolve a conflict ====

'''Warning:''' relocating these variables requires knowing which address to choose and accounting for the full memory footprint. A free starting address is not enough: the entire block must fit, and the routines must be able to access it. If you are unfamiliar with this, consult someone experienced before changing the addresses.

If another resource uses any of these areas, you can edit '''<code>ASM/DXDefines.asm</code>''' to make Dynamic Xtreme use other available space in your ROM hack.

* Change <code>!Variables</code> and <code>!Variables2</code> in the configuration matching your ROM: LoROM with <code>Free7E2000</code>, LoROM without it, or SA-1.
* On LoROM without <code>Free7E2000</code>, also check <code>!Variables3</code>, which determines where the <code>DX_FreeRams2</code> tables begin.
* Reserve enough space for the entire block and the sprite tables that follow. A free first address alone is not enough.
* Respect the memory map and the banks required by the routines. Not every free address works with every type of access.
* After changing the addresses, reinstall Dynamic Xtreme and reinsert PIXI, UberASM, and any other resources that use its defines.

With <code>Free7E2000</code>, Dynamic Xtreme uses the RAM recovered by relocating the original graphics; do not share it with other resources without checking which part is used. Without that option, the alternative addresses may overlap those of other common resources. SA-1 uses its own addresses and disables <code>Free7E2000</code>.

Edit the file in the '''ASM''' directory, not the generated copies in <code>ExtraDefines</code> or <code>Patch/ExtraDefines</code>: those copies are regenerated during installation.

== Resources made with Dynamic Xtreme ==

Resources developed for Dynamic Xtreme are not usually published on traditional sites such as SMW Central, because many depend directly on the framework and its advanced systems.

Instead, Dynamic Xtreme resources, examples, systems, and related projects are mainly collected at:

https://snestorage.dev

There you can find sprites, player systems, graphical effects, technical examples, and other resources designed specifically for Dynamic Xtreme.

== Conclusion ==

Dynamic Xtreme aims to modernize and simplify dynamic systems in Super Mario World, offering more flexible, powerful, and accessible tools while retaining compatibility and advanced control.

The project continues to evolve with new optimizations, formats, and tools for both experienced users and people just starting to work with dynamic graphics on SNES.

Dynamic Xtreme's main aim is to support increasingly complex resources and systems while keeping the workflow cleaner, easier to maintain, and more accessible to the community.

es/Dynamic Xtreme internal workings

2026-10-25T18:22:25Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_internal_workings}}

En este artículo se explica cómo funciona Dynamic Xtreme, desde la preparación de los recursos al instalarlo hasta la carga y el dibujo de una pose durante el juego.

== Qué prepara la instalación ==

Antes de que un sprite pueda usar sus gráficos o una paleta, Dynamic Xtreme tiene que guardarlos en la ROM y preparar la información para encontrarlos. Lo mismo ocurre con cualquier otro recurso dinámico que hayas añadido.

Para hacerlo, la herramienta lee los DynamicInfo, DrawInfo y PaletteEffect. Cada archivo aporta una parte distinta: qué recursos se van a cargar, cómo se dibujan las poses y qué cambios de color se pueden aplicar.

Gracias a esta preparación se generan defines en <code>DXDefines.asm</code> que permiten utilizar los recursos y ejecutar fácilmente las rutinas necesarias.

=== DynamicInfo: recursos y datos de carga ===

Un DynamicInfo reúne los gráficos de poses, las paletas y los recursos generales que necesita un sprite u otro código. Si incluye gráficos de poses dinámicas, la herramienta los organiza para que puedan cargarse con la distribución de tiles que espera el sistema.

Por cada pose guarda varios datos en tablas separadas. Todas mantienen el mismo orden: la entrada de una pose en una tabla corresponde a esa misma pose en las demás. En la tabla siguiente, '''N''' es la cantidad de poses dinámicas instaladas.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>PoseSize</code> || 2 × N || 2 || La cantidad de datos que utiliza cada pose, en bytes. Se utiliza para comprobar si su carga cabe en el presupuesto del frame.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Cuántos bloques de 16×16 hay que reservar en VRAM para la pose. No siempre coincide exactamente con los bytes que se copian, porque una pieza incompleta también puede necesitar un bloque de espacio.
|-
| <code>PoseResource</code> || 3 × N || 3 || La dirección de los gráficos de cada pose en ROM. Incluye el banco, de modo que el código de carga pueda encontrar su origen completo.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; dos valores por pose || Dos tamaños por pose, correspondientes a los dos tramos en que pueden dividirse sus gráficos. La rutina de carga utiliza esos tamaños para repartirlos correctamente en VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || El desplazamiento en VRAM desde el comienzo del primer tramo hasta el comienzo del segundo. Permite colocar el segundo tramo donde corresponde, aunque el primero termine con una fila incompleta.
|}

Estas tablas describen todas las poses instaladas, no solo las que están en pantalla. Más adelante, la caché guarda por separado cuáles están cargadas y dónde quedaron.

Por ejemplo, si se solicita una pose que todavía no está en VRAM, el sistema consulta cuántos bytes necesita cargar, busca espacio para sus bloques y utiliza la dirección y los datos de sus tramos para preparar la carga.

==== Tablas de paletas ====

Las paletas declaradas en los DynamicInfo se reúnen en <code>PaletteTable</code>. Si '''P''' es la cantidad de entradas de las listas de paletas de los DynamicInfo:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID de cada paleta.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || Dirección de sus colores en ROM.
|}

P cuenta las entradas de las listas, no solo las paletas distintas: una paleta compartida puede aparecer en más de un DynamicInfo.

Las dos listas siguen el orden de las paletas de los DynamicInfo. El define de offset de cada DynamicInfo indica dónde comienza su lista dentro de ellas. Al elegir una versión, el sistema suma ese índice al offset y obtiene tanto el ID como la dirección de los colores elegidos.

El ID permite reconocer y compartir una paleta; la dirección permite cargarla. No son el número de paleta de pantalla: una misma paleta instalada puede terminar, por ejemplo, en la paleta 9 o en la C según la asignación.

==== Recursos generales y defines ====

Los archivos declarados en <code>Resources</code> se guardan en ROM. Su dirección y la cantidad de bytes que ocupan pueden consultarse mediante los defines generados en <code>DXDefines.asm</code>. Por ejemplo, para <code>my_resource.bin</code> se generan:

* <code>!ResourceMyResource</code>: dirección del recurso en ROM.
* <code>!ResourceMyResourceSize</code>: cantidad de bytes que ocupa.
* <code>!ResourceIDMyResource</code>: ID del recurso.

El nombre se normaliza en PascalCase: se eliminan espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra.

=== DrawInfo: datos y rutinas de dibujo ===

El DrawInfo describe cómo está formada una pose: qué tiles tiene, dónde se coloca cada uno, qué tamaño utiliza y cómo cambia al voltearse.

Al instalarlo, Dynamic Xtreme genera rutinas de dibujo optimizadas según los parámetros que utilizan los tiles. Tiene en cuenta, por ejemplo, si necesitan desplazamientos X e Y, si comparten el mismo tamaño, si utilizan propiedades comunes y si requieren volteos.

De esta forma, la rutina realiza el trabajo que necesita ese dibujo sin añadir el manejo de opciones que no utiliza. Varias poses pueden compartirla si necesitan el mismo tratamiento; eso no significa que compartan también sus gráficos o su ID.

La relación entre una pose y su dibujo se guarda en estas tablas. '''D''' es la cantidad de poses de dibujo y '''R''' la cantidad de rutinas generadas:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>TableOffset</code> || 2 × D || 2 || Dónde comienzan los datos de la pose dentro de las tablas de su rutina de dibujo. Así se localizan sus tiles y desplazamientos sin recorrer las poses anteriores.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || La cantidad de tiles de la pose menos uno. Una pose de cuatro tiles guarda 3; la rutina utiliza ese valor para recorrer sus piezas.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Qué rutina de dibujo utiliza cada pose. Las poses con características compatibles pueden apuntar al mismo ID de rutina.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 por rutina || Las direcciones de las rutinas de dibujo. El ID de rutina permite encontrar aquí el código que debe ejecutarse.
|}

Cada rutina tiene, además, las tablas que necesitan sus poses. Aquí '''T''' es la cantidad de entradas de cada tabla de la rutina:

{| class="wikitable"
! Datos !! Bytes totales !! Bytes por valor !! Qué describen
|-
| <code>Tiles</code> || T, si se genera || 1 || Los números de tile que forman la pose.
|-
| <code>Properties</code> || T, si se genera || 1 || Las propiedades de cada pieza, como los volteos y su prioridad respecto a las capas.
|-
| <code>XDisplacements</code> y <code>YDisplacements</code> || T por tabla, si se genera || 1 || La posición de cada tile respecto al punto de origen de la pose.
|-
| Tablas de desplazamientos para los volteos || T por tabla, si se genera || 1 || Las posiciones que deben utilizarse al voltear la pose cuando necesita una distribución distinta.
|-
| <code>Sizes</code> || T, si se genera || 1 || El tamaño de cada tile: 8×8 o 16×16.
|}

No todas estas tablas tienen que aparecer en todas las rutinas. Si un dato es igual para todas las piezas o puede obtenerse de un valor común, la herramienta puede generar una rutina que lo utilice directamente.

La optimización se hace durante la instalación. Si todos los tiles tienen el mismo tamaño, por ejemplo, la rutina puede utilizar ese valor común sin leer un tamaño distinto para cada pieza.

=== PaletteEffect: datos de los efectos ===

Un archivo PaletteEffect contiene una lista de cambios de color. La instalación les asigna IDs y guarda sus datos en <code>PaletteEffectsTable</code>.

Como en las tablas de poses, los datos de cada efecto mantienen la misma posición en las distintas listas. Los IDs de efectos comienzan en 1; el ID 0 se utiliza para indicar que no hay efecto global. En la tabla, '''E''' es la cantidad de efectos instalados; el conjunto ocupa '''2 + 7 × E bytes'''.

{| class="wikitable"
! Parte de la tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>Length</code> || 2 || 2 || La cantidad de efectos instalados.
|-
| <code>Types</code> || E || 1 || El tipo de cada efecto, por ejemplo <code>MixH</code>, <code>MixS</code> o <code>PalTransitionRGB</code>. Indica qué cálculo debe realizarse.
|-
| <code>Value1</code>, <code>Value2</code> y <code>Value3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Los valores de los canales que utiliza el efecto. En una transición, estos tres bytes guardan la dirección de la paleta de destino, no valores de canales.
|-
| <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Cuánto se aplica el cambio en cada componente. Van de 0 a 127.
|}

Si el efecto es una transición hacia otra paleta, la herramienta también prepara esa paleta. Convierte sus colores al formato RGB o HSL que necesita la transición y los guarda en ROM. Durante el juego se puede utilizar ese destino sin tener que convertirlo de nuevo en cada llamada.

Estas paletas de transición son distintas de las paletas normales que se cargan a CGRAM: contienen tres componentes por color y se utilizan para calcular el efecto.

=== Cómo encuentra el código los recursos instalados ===

<code>DXDefines.asm</code> publica los IDs, direcciones, tamaños y offsets que necesitan los recursos. Por ejemplo, <code>!DynamicPoseIDMySpriteIdle</code> identifica una pose y <code>!PaletteEffectIDMyEffect0</code> identifica el primer efecto de un archivo.

Los nombres se normalizan en PascalCase: se eliminan separadores como espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra. <code>my_sprite</code>, por ejemplo, pasa a <code>MySprite</code>.

También se genera <code>BufferTable</code>, que guarda las direcciones de los bloques donde se insertaron los recursos. Cada dirección ocupa 3 bytes y se añade un valor final <code>$FFFFFF</code> de otros 3 bytes. Para B bloques, ocupa <code>3 × (B + 1)</code> bytes. La herramienta utiliza esa información para localizar los datos de una instalación anterior al reinstalar.

Una reinstalación puede cambiar IDs y direcciones. Por eso hay que volver a insertar los sprites, bloques y códigos UberASM que utilizan los defines generados.

== El trabajo de cada frame ==

En la lógica principal se ejecutan el jugador, los sprites y los demás códigos del modo de juego. Los que utilizan Dynamic Xtreme solicitan las poses y paletas que necesitan, preparan los efectos locales y llaman a las rutinas de dibujo. Las cargas que se aceptan quedan anotadas para transferir sus datos durante NMI.

Al terminar esa lógica, el código de game mode de Dynamic Xtreme realiza las tareas que correspondan a las opciones habilitadas: prepara las actualizaciones de VRAM de la optimización de Kevin, mantiene el estado de las paletas y calcula los efectos globales pendientes.

Después, durante NMI, Dynamic Xtreme realiza estas tareas en orden, según las funcionalidades habilitadas:

# Pone <code>DX_Dynamic_CurrentDataSend</code> en 0.
# Incrementa <code>DX_Timer</code>.
# Incrementa <code>DX_SyncTimer</code> si la acción no está congelada ni el juego está en pausa.
# Ejecuta las transferencias de gráficos a VRAM.
# Ejecuta las transferencias de colores a CGRAM.
# Actualiza el color 0,0 si el sistema de efectos tiene un resultado pendiente.

El orden que seguiremos para explicarlo es, por tanto, '''lógica principal → tareas al terminar el game mode → transferencias durante NMI'''.

=== Lógica principal ===

Cada recurso decide qué necesita. Un sprite puede cambiar de pose, una animación puede pedir nuevos gráficos y un código UberASM puede cargar una paleta o seleccionar un efecto.

Si la pose solicitada ya está cargada, Dynamic Xtreme actualiza su tiempo de último uso para protegerla del reemplazo y no vuelve a cargar sus gráficos. Si no está cargada, comprueba el presupuesto de datos del frame y busca espacio disponible en VRAM antes de preparar su carga.

El dibujo también se prepara en esta parte: las rutinas escriben en los buffers OAM la posición, los tiles y las propiedades de las piezas que se mostrarán.

Una solicitud puede rechazarse, por ejemplo si no queda presupuesto para sus datos. El recurso que la pidió debe comprobar el resultado y decidir si conserva lo anterior o vuelve a intentarlo después. Una carga rechazada no queda guardada automáticamente para otro frame.

=== Tareas de game mode ===

En esta parte se realizan las siguientes tareas, según las funcionalidades habilitadas.

'''Antes de ejecutar la lógica del juego:'''

# Si está habilitado <code>ControllerOptimization</code>, se ejecuta la rutina del control aquí en lugar de hacerlo en NMI.
# Se comprueba si Dynamic Xtreme debe funcionar en el game mode actual. Si no debe hacerlo, se reinician sus variables. Esto ocurre cada frame que se permanezca en un modo no permitido.

Después se ejecuta la lógica normal del juego, incluidos los sprites y los códigos que solicitan cargas o cambios de paleta.

'''Cuando termina esa lógica:'''

# Si está habilitada la optimización de VRAM de Kevin, se ajustan los destinos de las actualizaciones de Lunar Magic antes de que se transfieran.
# Se ponen en 0 los indicadores de actualización de las paletas y se resta 1 a sus temporizadores de protección si todavía son mayores que 0. Esta parte se omite durante la pausa y en los modos no permitidos.
# Se aplican los efectos globales a las paletas que necesitan actualizarse y se preparan las transferencias de sus colores. Esta parte también se omite si la comprobación anterior impide continuar.

Las copias a VRAM y CGRAM se realizan después, durante NMI. Aquí se deja preparado lo que se va a copiar.

=== Game modes permitidos ===

Dynamic Xtreme utiliza dos comprobaciones de game mode:

* '''Sistema general:''' <code>Routines_AllowedGameMode</code>, publicado como <code>!AllowedGameMode</code>. Se utiliza para decidir si se reinicializa el sistema, si se procesa su NMI y si se realizan las tareas de paletas. Las macros de asignación de paletas también consultan esta comprobación cuando necesitan procesar una carga del DynamicInfo.
* '''Rutinas de sprites:''' <code>DXAllowedGameMode</code> utiliza una tabla distinta. La carga de poses mediante <code>!Upload</code> y sus macros generales tiene una tabla con los mismos valores para decidir si procesa una solicitud nueva.

Por tanto, que el sistema general esté habilitado no significa que todas las funciones de sprites acepten cargas nuevas en ese modo. Esta tabla muestra las comprobaciones actuales; los IDs están en hexadecimal:

{| class="wikitable"
! Game mode !! Pantalla o etapa de SMW !! Sistema general !! DXAllowedGameMode / solicitudes nuevas de Upload
|-
| <code>$06</code> || Apertura del foco de la pantalla de título. || Sí || No
|-
| <code>$07</code> || Pantalla de título. || Sí || Sí
|-
| <code>$08</code> || Selección de partida. || Sí || No
|-
| <code>$09</code> || Borrado de partida. || Sí || No
|-
| <code>$0A</code> || Selección de uno o dos jugadores. || Sí || No
|-
| <code>$0C</code> || Carga del overworld. || Sí || No
|-
| <code>$0D</code> || Aparición gradual del overworld. || Sí || No
|-
| <code>$0E</code> || Overworld. || Sí || Sí
|-
| <code>$12</code> || Preparación del nivel. || Sí || No
|-
| <code>$13</code> || Aparición gradual del nivel. || Sí || No
|-
| <code>$14</code> || Juego dentro del nivel. || Sí || Sí
|-
| <code>$15</code> || Desvanecimiento hacia Game Over / Time Up. || Sí || No
|-
| <code>$1B</code> || Escena de castillo o créditos. || No || Sí
|-
| <code>$1C</code> || Desvanecimiento hacia la casa de Yoshi de los créditos. || Sí || No
|-
| <code>$1D</code> || Carga de la casa de Yoshi de los créditos. || Sí || No
|-
| <code>$1E</code> || Aparición gradual de la casa de Yoshi de los créditos. || Sí || No
|-
| <code>$1F</code> || Casa de Yoshi de los créditos. || Sí || Sí
|-
| <code>$24</code> || Aparición gradual de la presentación de enemigos. || Sí || No
|-
| <code>$25</code> || Presentación de enemigos de los créditos. || Sí || Sí
|-
| <code>$29</code> || Pantalla «The End». || No || Sí
|-
| Los demás valores entre <code>$00</code> y <code>$2F</code>. || — || No || No
|}

Los nombres de las etapas corresponden a los [https://github.com/IsoFrieze/SMWDisX/blob/master/bank_00.asm game modes de SMW documentados en SMWDisX]; los permisos se obtienen de las tablas de Dynamic Xtreme.

Cuando <code>Upload</code> no permite una solicitud nueva, comprueba si el recurso conserva una pose anterior. Si existe, actualiza su tiempo de último uso y devuelve carry activado; si no existe, devuelve carry desactivado. No solicita otra pose en ese camino.

Los modos <code>$1B</code> y <code>$29</code> muestran por qué deben distinguirse ambas columnas: pasar la comprobación de sprites no habilita el NMI del sistema general ni evita que el game mode reinicialice sus variables. La columna de sprites no debe interpretarse como una garantía de funcionamiento completo en esos modos.

=== Transferencias durante NMI ===

NMI es una interrupción que SNES puede generar al comenzar VBlank, después de dibujar la parte visible de la pantalla. El juego aprovecha ese intervalo para actualizar gráficos, colores y otros datos de video.

En los modos permitidos, la rutina de Dynamic Xtreme realiza estas tareas en orden, según las funcionalidades habilitadas:

# Pone <code>DX_Dynamic_CurrentDataSend</code> en 0 para contar las solicitudes del siguiente ciclo de lógica. Las transferencias ya preparadas siguen guardadas en sus listas.
# Incrementa <code>DX_Timer</code>.
# Comprueba <code>$9D</code> y <code>$13D4|!addr</code>. Si ambos están en 0, incrementa <code>DX_SyncTimer</code>.
# Ejecuta las transferencias pendientes a VRAM, si está habilitado <code>GraphicsChange</code>.
# Ejecuta las transferencias pendientes a CGRAM, si está habilitado <code>PalettesChange</code>.
# Si está habilitado <code>PalettesEffects</code>, ejecuta la actualización del color 0,0 cuando hay un resultado pendiente.

Para realizar las copias se utiliza DMA. NMI lee cada carga de las listas, configura desde dónde se copiarán los datos, cuántos bytes se copiarán y dónde se colocarán, y ejecuta la transferencia.

El tiempo de VBlank es limitado y SMW también lo necesita para sus actualizaciones de pantalla. Para limitar la cantidad de datos enviados en un frame y evitar flickering, Dynamic Xtreme utiliza <code>DX_Dynamic_CurrentDataSend</code>, que cuenta los bytes de las cargas solicitadas, y <code>DX_Dynamic_MaxDataPerFrame</code>, que establece el límite permitido. Antes de aceptar una carga normal, se comprueba que sus bytes no hagan superar ese límite.

==== Las listas de transferencias ====

Cada transferencia guarda el origen de los datos, su banco, la cantidad de bytes y el destino en VRAM o CGRAM.

Al realizar las copias, NMI recorre las listas desde la última entrada hacia la primera y después las vacía. Esto no borra los gráficos o colores cargados: permanecen en su destino hasta que otro código los cambie.

La lista de VRAM utiliza 0 cuando no tiene entradas. La de CGRAM utiliza <code>$FF</code>, porque guarda el índice de la última entrada en lugar de guardar directamente su cantidad.

Si dos códigos escriben sobre el mismo destino, deben coordinar sus cargas. El orden de las solicitudes no debe utilizarse como sustituto de decidir qué recurso puede ocupar cada espacio.

Normalmente, el recurso se lee desde ROM. Si el recurso se encuentra en un buffer en RAM, el usuario debe conservar su contenido hasta que NMI realice la transferencia. Por ejemplo, si prepara una paleta en RAM, no debe modificar ni reutilizar ese buffer antes de que se copie. La lista guarda su dirección, no una copia de sus datos; Dynamic Xtreme no protege el buffer contra cambios realizados por otros códigos.

==== Presupuesto de datos ====

Las macros de transferencia, como <code>%TransferToVRAM()</code> y <code>%TransferToCGRAM()</code>, comprueban cuántos bytes se han solicitado mediante <code>DX_Dynamic_CurrentDataSend</code>. Si al añadir la nueva carga se supera <code>DX_Dynamic_MaxDataPerFrame</code>, la rechazan. Si la aceptan, suman sus bytes al contador.

El límite predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Su objetivo es evitar flickering por enviar demasiados datos en un mismo frame. Es un límite de cantidad de datos, no una medida exacta del tiempo que tarda cada transferencia.

Estas macros tienen variantes como <code>%ForcedTransferToVRAM()</code> y <code>%ForcedTransferToCGRAM()</code>, que aceptan la carga sin comprobar si supera el límite. Sus bytes también se suman a <code>DX_Dynamic_CurrentDataSend</code>, por lo que reducen lo que queda disponible para las siguientes cargas normales. Se utilizan para cargas prioritarias, como las del jugador; usarlas no evita el flickering si se solicita una cantidad excesiva de datos.

Para consultar la diferencia entre el presupuesto de bytes y la capacidad de las listas, las restricciones de las transferencias y las comprobaciones que debe realizar tu código, consulta [[es/Dynamic_Xtreme_ASM_API#PPU|PPU en la API ASM]].

==== Los dos relojes ====

'''DX_Timer: protección de las solicitudes'''

<code>DX_Timer</code> avanza cuando se ejecuta la parte de NMI de Dynamic Xtreme. Además de medir cuánto lleva una pose sin utilizarse, sirve para evitar que un recurso repita sus solicitudes antes de que se procesen las anteriores.

No siempre hay un ciclo de lógica por cada ejecución completa de NMI. Durante slowdown, SMW puede ejecutar una versión reducida de NMI, y puede haber dos ciclos de lógica sin que entre ellos se hayan procesado las listas de transferencias de Dynamic Xtreme.

Sin una protección, un recurso podría añadir otra vez sus cargas a esas listas. Las solicitudes repetidas ocuparían más espacio y podrían provocar flickering.

Para evitarlo, las rutinas de carga de poses para sprites comparan <code>DX_Timer</code> con el valor de dos bytes guardado por ese sprite, normalmente llamado <code>SafeFrame</code>. En los aliases de sprites se utiliza <code>!SafeFrameLowByte,x</code> y <code>!SafeFrameHighByte,x</code>.

El proceso es el siguiente:

# '''Compara los relojes.''' Si <code>SafeFrame</code> coincide con <code>DX_Timer</code>, ese sprite ya procesó su carga de poses con ese valor del reloj. La rutina omite una nueva solicitud.
# '''Guarda el intento antes de procesarlo.''' Si los valores son distintos, copia <code>DX_Timer</code> a <code>SafeFrame</code> y después comprueba si puede reutilizar la pose o necesita solicitar otra.
# '''Comprueba el resultado.''' Si necesita una pose nueva, la solicitud puede aceptarse o rechazarse. Aunque sea rechazada, el valor guardado en <code>SafeFrame</code> no se deshace.

Por tanto, <code>SafeFrame</code> indica '''cuándo se procesó el último intento''', no cuándo se consiguió cargar una pose. Si la carga falla, volver a ejecutar la rutina con el mismo <code>DX_Timer</code> no permite intentarla otra vez, aunque entre ambas llamadas haya cambiado la pose deseada o el espacio disponible.

En <code>!Upload</code> y <code>!UploadWithoutPoseOffset</code>, tanto una solicitud rechazada como una llamada omitida por esta protección utilizan el mismo camino de respaldo:

* Si <code>!LastPoseHashIndex,x</code> es distinto de <code>$FF</code>, actualizan el tiempo de último uso de esa pose para protegerla del reemplazo y devuelven carry activado. El sprite puede seguir dibujando la última pose disponible.
* Si contiene <code>$FF</code>, no existe una pose de respaldo y devuelven carry desactivado.

Por ejemplo, durante slowdown puede ocurrir esta secuencia:

# <code>DX_Timer = $0030</code>. El sprite guarda <code>$0030</code> en su <code>SafeFrame</code> e intenta obtener una pose nueva. No queda presupuesto de datos y la solicitud falla; conserva la pose anterior si tiene una.
# SMW ejecuta otro ciclo de lógica sin que se haya procesado el NMI de Dynamic Xtreme. El reloj sigue en <code>$0030</code>. La siguiente llamada del mismo sprite detecta la coincidencia y no repite la solicitud.
# Cuando se ejecuta el NMI de Dynamic Xtreme, <code>DX_Timer</code> avanza a <code>$0031</code>. En la siguiente llamada, los relojes ya no coinciden y el sprite puede volver a intentarlo. La solicitud rechazada no se reintenta sola: el código del sprite debe volver a llamar a la rutina.

Esta protección está activada en los aliases de carga de poses para sprites. En [[es/Dynamic_Xtreme_ASM_API#GeneralUpload|GeneralUpload]] y [[es/Dynamic_Xtreme_ASM_API#Upload (macro general)|Upload (macro general)]] se controla con <code>safeCheck</code>; el respaldo de la pose anterior se controla por separado con <code>checkLast</code>. [[es/Dynamic_Xtreme_ASM_API#TakeDynamicRequest|TakeDynamicRequest]] y las [[es/Dynamic_Xtreme_ASM_API#PPU|macros de transferencia PPU]] no realizan esta comprobación de <code>SafeFrame</code> por ti.

<code>DX_Timer</code> continúa avanzando durante la pausa cuando se ejecuta esa parte de NMI.

'''DX_SyncTimer: animaciones sincronizadas'''

La función principal de <code>DX_SyncTimer</code> es dar a los sprites un reloj común para sus animaciones. Por ejemplo, varios sprites que utilizan las mismas poses pueden calcular con este reloj qué pose les corresponde cada cuatro frames.

Así todos cambian al mismo tiempo y solicitan la misma pose. La primera solicitud puede necesitar cargarla; las demás la reutilizan sin programar otra carga de sus gráficos. Esto ahorra transferencias DMA y datos enviados por frame.

Si cada sprite llevara un reloj independiente, podrían terminar usando poses distintas de la misma animación al mismo tiempo y necesitar más cargas y espacio de VRAM.

<code>DX_SyncTimer</code> se detiene durante la pausa y cuando se congela la acción, para que las animaciones sincronizadas también se detengan.

== Carga de gráficos: GraphicsChange ==

<code>GraphicsChange</code> guarda en RAM una lista de solicitudes de carga. Durante NMI se recorren esas solicitudes y se copian sus datos a VRAM.

=== Variables de la lista ===

En esta tabla, '''V''' es el valor de <code>!VRAMTransferSize</code>: 64 por defecto. Las cuatro tablas de solicitudes reservan V bytes cada una; con entradas de 2 bytes, ese valor deja espacio para 32 solicitudes. Junto con el contador, reservan <code>1 + 4 × V</code> bytes: 257 por defecto.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Cantidad de solicitudes pendientes. El valor 0 indica que la lista está vacía.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 por defecto || 2 || Dirección de origen de cada solicitud, sin el banco.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 por defecto || 2 reservados; banco de 1 byte || Banco del origen.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 por defecto || 2 || Cantidad de bytes que se copiarán.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 por defecto || 2 || Dirección de destino en VRAM.
|}

Las tablas mantienen el mismo orden: la primera entrada de cada tabla pertenece a la primera solicitud, la segunda a la segunda, etc. Cada entrada de estas tablas ocupa 2 bytes, por lo que se avanza con desplazamientos de <code>$00</code>, <code>$02</code>, <code>$04</code>, etc.

Estos nombres representan direcciones de RAM calculadas en <code>DXDefines.asm</code>. Sus direcciones pueden cambiar según la configuración y las funcionalidades habilitadas.

=== Añadir una solicitud ===

La macro <code>%TransferToVRAM()</code> realiza los siguientes pasos:

# Calcula cuántos bytes habría en total al añadir la nueva carga a <code>DX_Dynamic_CurrentDataSend</code>.
# Compara el resultado con <code>DX_Dynamic_MaxDataPerFrame</code>. Si lo supera, devuelve el carry desactivado y no añade la solicitud.
# Utiliza <code>DX_PPU_VRAM_Transfer_Length</code> para encontrar la siguiente entrada y aumenta ese contador en 1.
# Guarda el origen, banco, cantidad de bytes y destino en las tablas.
# Actualiza <code>DX_Dynamic_CurrentDataSend</code> con los bytes de la carga y devuelve el carry activado.

<code>%ForcedTransferToVRAM()</code> guarda los mismos datos, pero no comprueba el límite de bytes. Las variantes <code>FromAddr</code> y <code>Resource</code> facilitan obtener el origen desde una dirección completa o desde los defines de un recurso.

Añadir una solicitud no copia los gráficos inmediatamente: deja la información preparada para NMI.

=== Ejecutar las solicitudes durante NMI ===

La rutina <code>VRAMDMA</code>:

# Lee <code>DX_PPU_VRAM_Transfer_Length</code>. Si es 0, termina porque no hay solicitudes.
# Calcula el desplazamiento de la última entrada: <code>(Length - 1) × 2</code>.
# Lee su origen, banco y cantidad de bytes, y los coloca en los registros de DMA.
# Escribe el destino de VRAM en <code>$2116-$2117</code> e inicia la transferencia mediante <code>$420B</code>.
# Retrocede 2 bytes para procesar la solicitud anterior. Repite hasta completar la primera.
# Escribe 0 en <code>DX_PPU_VRAM_Transfer_Length</code> para indicar que la lista está vacía.

'''La lista se ejecuta del final al inicio.''' No hace falta borrar todos sus datos al terminar: al quedar su largo en 0, la próxima solicitud volverá a utilizar la primera entrada.

=== Animaciones con un destino fijo ===

El código de una animación debe:

# Elegir la imagen que corresponde al paso actual.
# Calcular su dirección de origen.
# Solicitar la copia al destino de VRAM de la animación.
# Comprobar el carry. Si se rechaza la carga, conservar la imagen anterior y volver a intentarlo.

El destino puede ser siempre el mismo. Lo que cambia es la imagen que se copia allí; la lista de transferencias no decide cuándo debe avanzar la animación.

Puedes ver un código completo en [[es/Dynamic_Xtreme_UberASM_guide#Crear_animaciones_de_gráficos|Crear animaciones de gráficos de la guía de UberASM]].

=== Carga de una pose dinámica ===

La carga de una pose utiliza la caché para no repetir transferencias de gráficos que ya están disponibles:

# Busca el ID en la tabla hash.
# Si ya está registrado, actualiza su tiempo de uso y no añade otra carga.
# Si no está, comprueba la cantidad de bytes y busca un espacio adecuado en el mapa de VRAM.
# Elige qué poses pueden reemplazarse, teniendo en cuenta su tiempo sin uso y el espacio que necesita la nueva.
# Actualiza las tablas de la caché y el mapa.
# <code>DynamicRoutine</code> divide los datos de la pose en las transferencias necesarias.
# NMI ejecuta esas transferencias.

Cada paso se desarrolla en [[#Sprites_dinámicos:_DynamicPoses|Sprites dinámicos: DynamicPoses]], incluyendo la búsqueda por hash, el mapa, la política de reemplazo y la división de la carga en filas.

== Carga y asignación de paletas: PalettesChange ==

El sistema distingue dos valores:

* '''ID de paleta:''' identifica los colores guardados en ROM.
* '''Color de destino:''' indica desde qué color de la paleta de colores de CGRAM se colocarán los colores que se carguen. Por ejemplo, <code>$91</code> comienza en el color 1 de la paleta 9.

La asignación automática permite compartir colores entre sprites sin exigir un destino fijo para cada uno.

=== Lista de cargas a CGRAM ===

En esta tabla, '''C''' es <code>!CGRAMTransferSize</code>: 64 por defecto. El conjunto reserva <code>1 + 7 × C</code> bytes, es decir, 449 con ese valor. Aunque <code>SourceBNK</code> reserva 2 × C bytes, el código utiliza un byte de banco por solicitud.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Índice de la última solicitud pendiente. <code>$FF</code> indica una lista vacía; 0 indica que hay una solicitud.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 por defecto || 2 || Dirección de origen, sin el banco.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 reservados por defecto || 1 utilizado por solicitud || Banco del origen.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 por defecto || 2 || Cantidad de bytes que se copiarán. Cada color ocupa 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 por defecto || 1 || Primer color de destino en CGRAM.
|}

Durante NMI, <code>CGRAMDMA</code>:

# Comienza por la última solicitud pendiente.
# Configura DMA con el origen y la cantidad de bytes de esa solicitud.
# Selecciona el primer color mediante <code>$2121</code> y realiza la copia.
# Continúa con las solicitudes anteriores.
# Al terminar, escribe <code>$FF</code> en <code>DX_PPU_CGRAM_Transfer_Length</code>.

Las macros <code>TransferPalette</code> también actualizan las copias de colores y el estado de efectos:

* '''Sin efecto global:''' solicitan la carga y actualizan los buffers de SMW. Así el juego no vuelve a utilizar colores anteriores durante la animación de victoria del goal.
* '''Con efecto global:''' guardan los colores originales y preparan el estado necesario para aplicarles el efecto antes de enviarlos a CGRAM.

=== Asignación automática ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || Guarda el ID asignado a cada destino. <code>$FFFF</code> indica una entrada libre y <code>$FFFE</code> una reservada.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protege cada destino del reemplazo automático mientras está en uso.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; un bit por paleta de sprites || Indica qué paletas de sprites están asignadas con efecto global habilitado. Esta condición también se compara al compartir una asignación.
|}

La búsqueda sigue este orden:

# Reutilizar una asignación con el mismo ID y una condición de efecto compatible.
# Si no existe, utilizar una entrada libre.
# Si no hay entradas libres, reemplazar una que no esté reservada y cuyo temporizador sea 0.
# Si no encuentra ninguna, indicar que la asignación falló.

Mientras el recurso utiliza la paleta, mantiene su temporizador en 2. Llegar a 0 no borra los colores: la asignación puede reutilizarse si otro recurso todavía no la reemplazó.

=== Asignación manual y versión ===

* '''Manual con carga:''' el código elige el destino y solicita sus colores.
* '''Manual sin carga:''' el código elige el destino y utiliza los colores que ya estaban preparados.
* '''Versión:''' selecciona una entrada de la lista de paletas del DynamicInfo. La última versión procesada permite comprobar si esa selección cambió.

Dos recursos que elijan el mismo destino con colores distintos deben coordinarse. Mantener la protección de una paleta no significa volver a cargar sus colores.

== Dibujo de poses: DrawingSystem ==

El dibujo prepara las piezas de una pose en OAM: qué tiles se muestran, dónde se colocan y qué propiedades utilizan. Los datos gráficos deben estar en VRAM.

=== Pasos del dibujo ===

# Busca la rutina y los datos de la pose mediante <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code> y <code>TableOffset</code>.
# Obtiene la cantidad de piezas desde <code>NumberOfTilesMinus1</code>.
# Calcula la posición de cada tile usando la posición del sprite, sus desplazamientos y los volteos que correspondan.
# Comprueba si la pieza puede verse y si queda espacio de OAM.
# Escribe su posición, número de tile, propiedades y tamaño en los buffers OAM.

El número de tile depende del dibujo:

{| class="wikitable"
! Caso !! Cómo se obtiene el tile
|-
| Pose dinámica || Se ajusta al lugar de VRAM donde quedaron cargados sus gráficos.
|-
| Pose estática || Se utiliza su número de tile fijo.
|-
| Pose que utiliza un tile común || El código debe preparar <code>!Tile</code> antes de llamar al dibujo.
|}

=== Prioridad y espacio disponible ===

* En '''LoROM''', el sistema lleva su propio control de entradas OAM disponibles.
* En '''SA-1''', utiliza la integración con MaxTile.
* La '''prioridad de dibujo''' organiza las piezas de sprites. No es la misma propiedad que determina si un tile queda delante o detrás de las capas.
* Los '''límites por línea de pantalla''' de SNES siguen existiendo. Tener una pose cargada no garantiza que puedan verse todas sus piezas.

== Jugador y Yoshi ==

=== PlayerFeatures ===

El jugador original tiene rutinas propias para elegir y cargar las piezas de sus poses. <code>PlayerFeatures</code> permite integrar ese trabajo con las cargas de Dynamic Xtreme y cambiar el origen de sus gráficos y paletas.

Con el formato original, el juego sigue eligiendo las piezas de la pose. La rutina obtiene sus direcciones desde el origen configurado y compara esas direcciones con las anteriores para cargar las que hayan cambiado.

Estas cargas utilizan transferencias forzadas y sus bytes también cuentan para las solicitudes normales posteriores. Así conservan su prioridad sin quedar fuera de la contabilidad del sistema.

La paleta del jugador tiene un tratamiento especial: combina colores y selecciones del propio juego con el origen personalizado. No funciona simplemente como sustituir una paleta completa de un sprite cualquiera.

El soporte para jugadores personalizados permite que otros sistemas administren de otra forma sus poses y dibujo. No convierte automáticamente cualquier spritesheet al formato del jugador original.

=== YoshiFeatures ===

Yoshi también carga sus gráficos por piezas. <code>YoshiFeatures</code> permite cambiar su origen manteniendo la organización que esperan sus rutinas.

El código calcula qué partes necesita y prepara sus cargas a los destinos correspondientes de VRAM. Como las del jugador, estas cargas tienen un tratamiento prioritario.

Esta opción necesita <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad. No permite evitar un conflicto del sistema del jugador habilitando únicamente las funciones de Yoshi.

== Memoria y optimizaciones ==

=== Free7E2000 ===

SMW mantiene en RAM gráficos originales del jugador, Yoshi y ciertas animaciones. En ROMs sin SA-1, esta opción adapta las cargas para leer esos datos desde ROM.

Dynamic Xtreme aprovecha la RAM recuperada para sus variables internas. No es un espacio que quede libre para que cualquier otro código escriba encima.

SA-1 utiliza otras direcciones y desactiva esta opción. Los rangos están en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Espacios de RAM utilizados]].

=== ControllerOptimization ===

Esta opción mueve el procesamiento del control desde NMI a la parte de game mode. El objetivo es dejar más tiempo para las actualizaciones de pantalla, no añadir un frame de retraso ni cambiar los botones que recibe el juego.

=== FixedColorOptimization ===

El color fijo se utiliza en las mezclas de color de la consola. Para actualizarlo, el juego prepara sus componentes y los envía al registro correspondiente.

La optimización reemplaza esa preparación por una secuencia más corta. El color sigue enviándose a la consola, pero necesita menos trabajo durante NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic utiliza listas llamadas stripe images para actualizar partes de los mapas de tiles. Esas listas incluyen tanto los datos como la información sobre sus destinos.

La versión integrada de la optimización de Kevin prepara fuera de NMI parte del ajuste de esos destinos. Así deja menos trabajo de preparación para el momento de la transferencia.

Esta opción sustituye el uso del parche original por separado. Además, no debe desinstalarse después de instalarla; hay que tenerlo en cuenta antes de activarla.

=== StatusBarOptimization ===

La barra de estado original actualiza zonas concretas de VRAM. Esta opción prepara sus transferencias de forma más directa, reduciendo la configuración de DMA que necesita hacer durante NMI.

No añade una barra nueva. Modifica la actualización de la original y, por eso, entra en conflicto con recursos que la reemplazan, modifican o eliminan.

== Sprites dinámicos: DynamicPoses ==

El sistema funciona como una '''caché de poses en VRAM'''. No reserva una copia de los gráficos para cada sprite: guarda la pose y permite que la reutilicen todos los recursos que la necesiten.

* Una pose se carga una sola vez mientras permanezca en la caché.
* Las siguientes solicitudes actualizan su tiempo de último uso, sin añadir otra carga de sus gráficos.
* La pose no se borra cuando un recurso deja de utilizarla. Permanece allí hasta que se necesite su espacio y se elija reemplazarla.
* Si fue reemplazada y vuelve a solicitarse, tendrá que cargarse otra vez.

La elección no depende de cuánto tiempo lleva la pose desde que se cargó, sino de '''cuánto tiempo lleva sin utilizarse''' y de si su espacio sirve para la pose nueva.

=== Tres valores distintos ===

{| class="wikitable"
! Valor !! Qué identifica
|-
| ID de pose || La pose instalada. Tiene 16 bits y permite consultar sus datos en ROM.
|-
| Índice de la tabla hash || La entrada de RAM donde se registró la pose. Va de 0 a 127.
|-
| Bloque de VRAM || ID de una de las 128 posiciones para tiles de 16×16 que caben en el espacio de VRAM de sprites. Se numeran de izquierda a derecha y de arriba abajo, desde 0 hasta 127. Para una pose que ocupa varios bloques, se guarda el ID de su primer bloque.
|}

El índice de la tabla hash y el bloque de VRAM no tienen por qué coincidir. Una entrada de la tabla puede registrar una pose que empieza en cualquier bloque permitido.

=== Tablas de las poses registradas ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Cantidad de poses registradas.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Cantidad de poses registradas para cada hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || ID completo de la pose de cada entrada. <code>$FFFF</code> indica una entrada libre.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Bloque de VRAM donde comienza cada pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || Valor de <code>DX_Timer</code> de su último uso.
|}

Estas tablas ocupan '''769 bytes''' en RAM. Guardan las poses registradas durante el juego; las tablas generadas desde el DynamicInfo describen, en cambio, todas las poses instaladas.

=== Cómo se busca una pose ===

La rutina <code>DynamicPoseHashmap_FindPose</code> utiliza una tabla hash de 128 entradas. El hash permite elegir dónde empezar a buscar:

<pre>
hash = ID de pose AND $007F
</pre>

Dos IDs diferentes pueden tener el mismo hash. Por ejemplo, <code>$0005</code> y <code>$0085</code> producen <code>$05</code>. Por eso el hash no basta para confirmar que la pose está cargada: también se compara el ID completo.

La búsqueda sigue estos pasos:

# Guarda el ID solicitado y calcula su hash.
# Si <code>DX_Dynamic_Pose_Length</code> es 0, no hay poses registradas y la búsqueda termina.
# Consulta <code>DX_Dynamic_Pose_HashSize[hash]</code>. Si es 0, ninguna pose registrada tiene ese hash y también termina.
# Comienza por la entrada cuyo índice coincide con el hash.
# Lee el ID de esa entrada. Si coincide con el solicitado, encontró la pose.
# Si no coincide, continúa con la siguiente entrada de la secuencia de búsqueda.

La secuencia avanza '''15 entradas por intento''' y vuelve al comienzo al superar 127:

<pre>
siguiente índice = (índice actual + 15) AND $7F
</pre>

Con 128 entradas, ese paso permite visitar todas las posiciones antes de repetir una. Para el hash <code>$05</code>, el comienzo de la secuencia es:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

==== El contador de poses de cada hash ====

Cada hash tiene su propio contador en <code>DX_Dynamic_Pose_HashSize</code>. Por ejemplo, si hay dos poses registradas cuyo ID produce el hash <code>$05</code>, la entrada <code>DX_Dynamic_Pose_HashSize+$05</code> contiene 2.

Ese número indica '''cuántas poses con ese hash existen''', no cuántas posiciones hay que recorrer. La búsqueda utiliza una copia temporal del contador:

# Comienza con la cantidad de poses registrada para el hash solicitado.
# Recorre las posiciones de la secuencia hasta encontrar el ID solicitado o haber comprobado esa cantidad de poses con el mismo hash.
# Cada vez que encuentra una pose con ese hash, pero con otro ID, resta 1 al contador temporal.
# Las posiciones libres y las poses de otros hashes no descuentan nada: continúa buscando.
# Si el contador temporal llega a 0 sin encontrar el ID, la pose solicitada no está registrada y la búsqueda termina.

El contador de <code>DX_Dynamic_Pose_HashSize</code> no se modifica durante esta búsqueda. Solo se actualiza al añadir o retirar poses de la caché.

Por ejemplo, se busca <code>$0105</code>, que produce el hash <code>$05</code>, y el contador de ese hash vale 2:

{| class="wikitable"
! Posición visitada !! ID guardado !! Hash del ID !! Poses del hash $05 que faltan por comprobar
|-
| <code>$05</code> || <code>$0005</code> || <code>$05</code> || 1: tiene el mismo hash, pero no es el ID solicitado.
|-
| <code>$14</code> || <code>$0014</code> || <code>$14</code> || 1: es otro hash, así que no se descuenta.
|-
| <code>$23</code> || <code>$0085</code> || <code>$05</code> || 0: ya se comprobaron las dos poses con ese hash. <code>$0105</code> no está registrada.
|}

Lo habitual es que haya una o dos poses por hash. Esto permite resolver la búsqueda con pocas comprobaciones y un coste normalmente cercano a <code>O(1)</code>. No significa que siempre se visiten solo una o dos posiciones: puede haber entradas de otros hashes entre ellas. Con muchas colisiones, el recorrido puede ser más largo.

'''Una entrada libre no termina la búsqueda.''' Puede haber quedado vacía al reemplazar una pose y existir otra del mismo hash más adelante. El contador permite saber cuándo ya se comprobaron todas las poses de ese hash, incluso si hay huecos entre ellas.

==== Cuando encuentra la pose ====

<code>TakeDynamicRequest</code>:

# Obtiene el índice de la entrada encontrada.
# Escribe el valor actual de <code>DX_Timer</code> en <code>DX_Dynamic_Pose_TimeLastUse</code> para esa entrada.
# Devuelve el éxito de la solicitud, sin volver a programar la carga de sus gráficos.

Así todos los recursos que solicitan ese ID utilizan la misma pose y la mantienen protegida. No importa si el recurso es un sprite normal, cluster, extended u otro código que utiliza el sistema.

Esto también evita duplicar una carga dentro del mismo ciclo: cuando la primera solicitud se acepta, la pose ya queda registrada aunque la transferencia física se vaya a realizar durante NMI.

=== Cuando la pose no está registrada ===

<code>TakeDynamicRequest</code> continúa con la preparación de una carga nueva:

# Consulta <code>PoseSize</code> y calcula <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# Si supera <code>DX_Dynamic_MaxDataPerFrame</code>, termina con fallo, sin cambiar las poses existentes.
# Consulta <code>Pose16x16Blocks</code> para saber cuántos bloques necesita.
# Llama a <code>VRAMMap_GetBestSlot</code> para buscar un espacio adecuado.
# Si no existe un espacio utilizable, termina con fallo.
# Retira del mapa y de la tabla hash las poses que ocupen el espacio elegido.
# Busca una entrada libre de la tabla hash y registra la pose nueva.
# Actualiza el mapa de VRAM y el contador de datos del frame.
# Llama a <code>DynamicRoutine</code> para añadir las transferencias.

El presupuesto se comprueba antes de reemplazar poses. Si la nueva carga no cabe en el frame, no se libera espacio para una solicitud que no se puede atender.

==== Añadir y quitar entradas de la tabla hash ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> busca una entrada cuyo ID sea <code>$FFFF</code>, siguiendo la misma secuencia de pasos de 15.
* <code>DynamicPoseHashmap_Add</code> guarda el ID y su tiempo de uso, aumenta <code>DX_Dynamic_Pose_Length</code> y aumenta el contador de su hash.
* <code>DynamicPoseHashmap_Remove</code> escribe <code>$FFFF</code> en el ID retirado y reduce ambos contadores.

Retirar una entrada no borra por sí solo los píxeles de VRAM. Indica que esa pose dejó de estar disponible en la caché; las nuevas transferencias sobrescribirán el espacio elegido.

=== Cómo se representa el mapa de VRAM ===

El mapa representa '''128 posiciones de tiles de 16×16 en la VRAM de sprites''', numeradas de izquierda a derecha y de arriba abajo. Cada bloque es una de esas posiciones, no un tramo de 128 bytes contiguos.

Un tile de 16×16 está formado por cuatro tiles de 8×8 distribuidos en dos filas. El mapa administra las posiciones que ocupa la pose; la distribución de sus datos para cargarlos se resuelve después en <code>DynamicRoutine</code>.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Posición donde comienza la sección. El bit <code>$80</code> indica que está restringida: ese espacio no se utiliza para poses dinámicas.
|-
| <code>DX_Dynamic_Tile_Size</code>, también llamada <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || Si el bit <code>$80</code> está activo, los otros bits guardan la cantidad de posiciones de la sección menos uno. Si está desactivado, guardan el índice hash de la pose que ocupa la sección. Para saber si el espacio está restringido, se consulta <code>Offset</code>.
|}

Estas dos tablas ocupan '''256 bytes'''. Junto con las tablas de poses, el administrador utiliza '''1025 bytes''' de RAM, sin contar las listas de transferencias ni las scratch de trabajo.

=== Secciones del mapa ===

Una sección agrupa posiciones consecutivas del mapa que están restringidas, libres o utilizadas por una pose. Su información se guarda en '''la primera y la última posición'''. Esto permite saltar de una sección a la anterior sin revisar todas sus posiciones intermedias.

Los siguientes ejemplos muestran tres estados posibles para una sección de 6 posiciones, de <code>$20</code> a <code>$25</code>. Son casos alternativos, no tres secciones que ocupen el mismo espacio a la vez.

==== Ejemplo 1: sección restringida ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$A0</code> || <code>$80</code> indica restringida y <code>$20</code> indica dónde comienza.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || La sección tiene 6 posiciones: <code>($85 AND $7F) + 1 = 6</code>.
|}

Aunque el bit alto de <code>Size</code> esté activo, '''no es espacio libre para poses dinámicas''': el bit de restricción en <code>Offset</code> hace que se descarte. No se evalúa como una pose que pueda reemplazarse.

<code>DynamicPoseSpaceConfig</code> utiliza este tipo de sección para excluir las partes de SP1-SP4 que no deben utilizar los sprites dinámicos.

==== Ejemplo 2: sección libre ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || Comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || El bit <code>$80</code> indica el tamaño de una sección libre: <code>$05 + 1 = 6</code> posiciones.
|}

Esta sección sí está disponible. Puede alojar una pose que necesite hasta 6 posiciones; si se coloca una de 4, las otras 2 quedan como otra sección libre.

==== Ejemplo 3: sección utilizada por una pose ====

Supongamos que una pose de 6 bloques está registrada en la entrada hash <code>$07</code> y ocupa las posiciones <code>$20</code> a <code>$25</code>:

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || La sección comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$07</code> || El bit <code>$80</code> está desactivado: <code>$07</code> es el índice hash de la pose, no su cantidad de bloques.
|}

Para conocer la cantidad de posiciones y el tiempo sin uso:

# Se lee el ID de la pose en <code>DX_Dynamic_Pose_ID+$0E</code>. Se utiliza <code>$0E</code> porque cada ID ocupa 2 bytes y <code>$07 × 2 = $0E</code>.
# Con ese ID se consulta <code>Pose16x16Blocks</code>, que en este ejemplo contiene 6.
# Se consulta <code>DX_Dynamic_Pose_TimeLastUse+$0E</code> para calcular cuánto lleva sin utilizarse.

La entrada <code>DX_Dynamic_Pose_Offset+$07</code> guarda <code>$20</code>, relacionando esa pose registrada con su posición en VRAM.

=== Recorrido y búsqueda de espacio ===

<code>VRAMMap_GetBestSlot</code> comienza por la posición de tile de 16×16 <code>$7F</code>. Para recorrer el mapa:

# Lee <code>DX_Dynamic_Tile_Offset</code> de la posición actual.
# Obtiene el comienzo de la sección con <code>Offset AND $7F</code>.
# Evalúa esa sección y los espacios que pueda formar con otras secciones contiguas.
# Pasa a la posición <code>comienzo de la sección - 1</code>, que es la última posición de la sección anterior.
# Repite hasta llegar al comienzo del mapa.

Por ejemplo, si las últimas secciones comienzan en <code>$70</code>, <code>$60</code> y <code>$50</code>:

{| class="wikitable"
! Posición visitada !! Comienzo leído de Offset !! Próxima posición
|-
| <code>$7F</code> || <code>$70</code> || <code>$6F</code>
|-
| <code>$6F</code> || <code>$60</code> || <code>$5F</code>
|-
| <code>$5F</code> || <code>$50</code> || <code>$4F</code>
|}

Así recorre '''secciones completas''', no cada tile intermedio.

==== Qué se evalúa durante el recorrido ====

El espacio candidato puede ser '''una sección o varias secciones contiguas'''. En cada paso se comprueba:

* Si hay una sección restringida, no se utiliza ni se combina a través de ella.
* Si hay una pose protegida por su uso reciente, tampoco puede formar parte del espacio.
* Si el candidato todavía es pequeño, se puede continuar con una sección contigua para completar la cantidad de bloques necesaria.
* Si ya cabe la pose, se compara el candidato con el mejor encontrado: primero por su score de tiempo sin uso y después por el espacio suficiente más pequeño.

No se elige una sección solo por contener la pose con más tiempo sin uso. El '''espacio completo''' debe permitir cargar la pose nueva. La puntuación de varias secciones combinadas depende de la pose utilizada más recientemente dentro de ese espacio.

Durante la búsqueda se conservan estos datos temporales:

{| class="wikitable"
! Datos de trabajo !! Bytes totales !! Bytes por valor !! Para qué se usan
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 por campo || Comienzo, score y cantidad de bloques del espacio candidato actual.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 por campo || Los mismos campos para el mejor espacio encontrado.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Cantidad de bloques que necesita la pose nueva.
|}

Estos nombres utilizan scratch de trabajo, no RAM persistente adicional.

=== Política de reemplazo: tiempo sin uso y espacio suficiente ===

El sistema no elige simplemente la pose que se cargó primero. Utiliza el tiempo transcurrido desde su '''último uso''':

<pre>
tiempo sin uso = DX_Timer - TimeLastUse de la pose
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> obtiene el tamaño y una puntuación para cada región:

{| class="wikitable"
! Caso !! Puntuación y tratamiento
|-
| Región libre || <code>$FF</code>. Se favorece frente a regiones ocupadas.
|-
| Región ocupada || Tiempo sin uso, limitado a <code>$FE</code>.
|-
| Tiempo sin uso de 0 o 1 || No se puede reemplazar: la pose sigue protegida.
|-
| Región restringida || Se descarta: ese espacio no se utiliza para poses dinámicas.
|}

La protección exige '''al menos dos avances de <code>DX_Timer</code> sin utilizar la pose'''. Cada recurso que vuelve a solicitarla actualiza su tiempo de uso y vuelve a protegerla.

==== Por qué no siempre se reemplaza la pose con más tiempo sin uso ====

La pose nueva necesita espacio suficiente y contiguo. Un espacio pequeño no sirve por sí solo, aunque lleve mucho tiempo sin utilizarse.

Por ejemplo, para una pose nueva de 4 bloques:

{| class="wikitable"
! Espacio candidato !! Tiempo sin uso !! ¿Sirve?
|-
| Pose A: 2 bloques, sin espacio contiguo utilizable || 20 || No: solo deja 2 bloques.
|-
| Pose B: 4 bloques || 8 || Sí: puede alojar la pose nueva.
|}

En este caso se puede reemplazar B y conservar A. A lleva más tiempo sin uso, pero su espacio no permite atender la solicitud.

Si dos o más regiones contiguas pueden reemplazarse, el sistema puede considerarlas juntas. Para esa combinación:

* Suma sus cantidades de bloques.
* Utiliza la '''menor puntuación''' de las regiones combinadas, es decir, el menor tiempo sin uso.
* Si una está restringida o protegida, no puede utilizarla para completar el espacio.

Así una pose usada recientemente no puede quedar sobrescrita por combinarla con otra que lleva mucho tiempo sin uso.

==== Elegir entre candidatos válidos ====

# El candidato debe tener al menos la cantidad de bloques solicitada.
# Se prefiere la puntuación más alta: espacio libre o mayor tiempo sin uso.
# Si las puntuaciones son iguales, se prefiere el candidato con menos bloques, siempre que la pose quepa.
# Si puntuación y tamaño también coinciden, se conserva el candidato que ya se había elegido.

Las regiones se combinan durante la búsqueda cuando el candidato todavía es demasiado pequeño. No se juntan todas las regiones reemplazables sin tener en cuenta el tamaño solicitado.

=== Reemplazar y dividir la región elegida ===

Una vez elegido el espacio:

# <code>VRAMMap_RemovePosesInSpace</code> recorre sus regiones y retira de la tabla hash las poses que haya que reemplazar.
# <code>VRAMMap_RemoveSpace</code> representa el espacio elegido como una región libre, actualizando sus extremos.
# Se busca una entrada hash libre y se guarda el bloque de comienzo en <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registra la pose.
# <code>VRAMMap_AddPoseInSpace</code> escribe el índice hash de la pose y el comienzo de su región en el primer y último bloque.
# Si sobran bloques, crea otra región libre con el resto.

Si una región de 6 bloques aloja una pose de 4, quedan una región ocupada de 4 y una libre de 2. No se mueven las demás poses para compactar VRAM.

=== DynamicRoutine: preparar las transferencias de la pose ===

En este punto ya se eligió el espacio y se registró la pose. <code>DynamicRoutine</code> convierte esa asignación en solicitudes de transferencia.

Utiliza estos datos:

{| class="wikitable"
! Dato !! Cantidad consultada por pose !! Para qué sirve
|-
| Bloque de comienzo || 1 byte || Lugar elegido por el mapa de VRAM.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes de una tabla de 256 bytes || Convierte uno de los 128 bloques en un desplazamiento de VRAM.
|-
| <code>PoseResource</code> || 3 bytes || Dirección completa de los datos de la pose en ROM.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: dos valores de 2 || Cantidad de bytes del primer y del segundo tramo.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || Desplazamiento de VRAM para el segundo tramo.
|}

==== Convertir el bloque en una dirección de VRAM ====

Los bloques de 16×16 no se convierten simplemente en un desplazamiento lineal de bytes. Cada uno utiliza tiles de 8×8 distribuidos en las filas de VRAM.

<code>OffsetToVRAMOffset</code> contempla esa distribución. Por ejemplo:

{| class="wikitable"
! Bloque !! Desplazamiento !! Dirección de VRAM
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

Estas direcciones de VRAM están expresadas en palabras de 2 bytes, no en bytes. La rutina suma la base <code>$6000</code> utilizada para los gráficos de sprites.

==== Procesar los tramos y sus filas ====

# Obtiene el origen desde <code>PoseResource</code>.
# Procesa los bytes del primer tramo mediante <code>DynamicRoutineLine</code>.
# Si el segundo tramo tiene tamaño 0, termina.
# Si existe, adelanta el origen la cantidad de bytes del primer tramo.
# Suma <code>PoseSecondLineOffset</code> al desplazamiento de VRAM y procesa el segundo tramo.

<code>DynamicRoutineLine</code> divide cada tramo según las filas y el punto de comienzo. Para un destino V expresado en palabras de VRAM, prepara:

<pre>
Final de la primera fila = (V + $0100) AND $FF00
Bytes hasta ese final = (final de la primera fila - V) × 2
Destino de la segunda parte = final de la primera fila + $0100
Bytes de la segunda parte de un grupo = $0200 - bytes de la primera
</pre>

Los tamaños son cantidades de bytes, mientras que los destinos de VRAM están expresados en palabras. Por eso se multiplica por 2 al calcular cuántos datos caben hasta el final de una fila.

La rutina utiliza tres recorridos:

* <code>.EndLine</code>: añade una solicitud final con los bytes restantes.
* <code>.TwoLinesWithEndLine</code>: añade dos solicitudes para los datos restantes, cada una con su destino y cantidad de bytes.
* <code>.TwoLines</code>: añade dos solicitudes que suman <code>$0200</code> bytes, avanza el origen y los destinos y repite con los datos que faltan.

Hay un caso directo antes del recorrido general: si el destino comienza en un límite de <code>$0100</code> palabras y el tramo tiene al menos <code>$0200</code> bytes, la rutina utiliza <code>.EndLine</code> para preparar la copia del tramo completo en una solicitud.

Por ejemplo, un tramo de <code>$0200</code> bytes que comienza en <code>$6020</code> se divide así:

{| class="wikitable"
! Solicitud !! Origen !! Destino VRAM !! Bytes
|-
| Primera || Comienzo del tramo || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Segunda || Comienzo del tramo + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Las dos solicitudes copian los 512 bytes del tramo, respetando los destinos que calcula la distribución de filas. No son dos copias completas de la pose.

Cada solicitud utiliza estas tablas:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Por cada solicitud añadida aumenta <code>DX_PPU_VRAM_Transfer_Length</code>.

La cantidad total de bytes de la pose ya se comprobó y se añadió a <code>DX_Dynamic_CurrentDataSend</code> en <code>TakeDynamicRequest</code>. Esta parte divide esa carga en transferencias; no vuelve a contar la pose completa por cada solicitud.

<code>DynamicRoutine</code> '''no ejecuta DMA'''. Deja las solicitudes preparadas para que <code>VRAMDMA</code> las copie durante NMI.

=== Qué conserva el sprite ===

Las rutinas de sprites guardan el índice hash de la pose utilizable, no una copia independiente de sus gráficos. Ese índice permite consultar su bloque de VRAM y mantener actualizado su tiempo de uso.

Si una pose nueva no puede cargarse:

* Si existe una pose anterior válida, se mantiene y se actualiza su tiempo de uso para protegerla.
* Si nunca hubo una pose válida, no se debe dibujar como si la solicitud hubiera tenido éxito.
* En las llamadas con soporte para mantener la anterior, el carry puede indicar que todavía hay una pose utilizable aunque no se haya completado el cambio.

La animación y el movimiento siguen siendo responsabilidad del sprite. La caché se ocupa de reutilizar o preparar los gráficos solicitados.

=== Ejemplo: dos sprites solicitan la misma pose ===

Supongamos que dos sprites visibles, A y B, necesitan la pose dinámica <code>$0005</code>. Sus paletas ya están listas, la pose todavía no está en VRAM y hay espacio y presupuesto para cargarla.

# '''El sprite A solicita la pose.''' La búsqueda no encuentra <code>$0005</code> en la caché. El sistema elige un espacio, registra la pose y prepara las transferencias de sus gráficos. A guarda el índice de esa entrada en <code>!LastPoseHashIndex,x</code>. Los gráficos aún no se han copiado a VRAM.
# '''A prepara su dibujo.''' La rutina de dibujo utiliza la entrada registrada para calcular los tiles que corresponden a ese espacio de VRAM y escribe sus posiciones y propiedades en los buffers OAM.
# '''El sprite B solicita la misma pose.''' La búsqueda ya encuentra <code>$0005</code> registrada, aunque su transferencia siga pendiente. Actualiza su tiempo de último uso y no programa otra carga. B guarda el mismo índice de caché en su propia <code>!LastPoseHashIndex,x</code>.
# '''B prepara su dibujo.''' Escribe sus propias piezas en los buffers OAM, utilizando los mismos gráficos que A, pero con su posición, paleta y volteo.
# '''Durante NMI se actualizan los datos de video.''' Se realizan las transferencias pendientes de la pose a VRAM y el juego transfiere los buffers OAM. En la siguiente imagen, los dos sprites utilizan los mismos gráficos cargados.

Se prepara una sola carga de la pose, aunque dos sprites la utilicen. Esa carga puede necesitar varias transferencias DMA según cómo se distribuyan sus gráficos en VRAM.

En este ejemplo, que la pose esté '''disponible''' durante la lógica significa que ya tiene una entrada y un espacio asignados, con su carga preparada para NMI. Si sus gráficos ya estaban en VRAM, se reutilizan directamente y no hay que preparar otra transferencia.

Si la solicitud de A fuera rechazada, no se registraría la pose nueva ni quedaría su carga pendiente. A utilizaría su pose anterior si tiene una; de lo contrario, no dispondría de una pose para dibujar. B tendría que resolver su propia solicitud y no encontraría una entrada creada por el intento rechazado de A.

== Efectos de paleta: PalettesEffects ==

El sistema conserva los colores originales para poder cambiar de efecto, combinarlo con otro o volver a la paleta sin efecto. No debe utilizar el resultado ya afectado como si fuera la paleta original.

=== Buffers de colores ===

{| class="wikitable"
! Variable o buffer !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 por color || Colores de base en formato SNES, con 2 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 por color || Base separada en rojo, verde y azul, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 por color || Base separada en tono, saturación y luminosidad, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 por color || Resultado en formato SNES, listo para solicitar su copia a CGRAM. Corresponde al buffer de paletas del juego.
|}

=== Indicadores de cada paleta ===

Cada bit de estos indicadores corresponde a una paleta. Las variables <code>BG</code> cubren 0-7 y las <code>SP</code> cubren 8-F.

{| class="wikitable"
! Variables !! Bytes totales !! Bytes por valor !! Qué indican
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> y <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si ya se preparó la base de colores en formato SNES.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> y <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparado el resultado del efecto global.
|}

Estos indicadores evitan repetir conversiones y cálculos que siguen siendo válidos.

=== Preparar una base ===

# Se comprueba si la paleta ya tiene una base registrada.
# Si no la tiene, se obtienen los colores del buffer del juego. Una carga explícita, como <code>TransferPalette</code>, puede proporcionar esa base directamente.
# Se comprueba si el efecto necesita RGB o HSL.
# Si falta esa conversión, se prepara y se marca como disponible.

Si solo cambia el efecto, la base puede seguir siendo válida. Si cambian los colores originales, las llamadas de carga actualizan la base e invalidan las conversiones y resultados que deben calcularse otra vez.

=== Datos de un efecto ===

El ID permite consultar las tablas generadas durante la instalación:

* <code>Types</code>: cálculo que debe realizarse.
* <code>Value1</code>, <code>Value2</code> y <code>Value3</code>: valores de los canales o dirección de la paleta de destino de una transición.
* <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code>: cuánto se aplica cada cambio.

Los canales utilizan valores de 0 a 31. Los ratios van de 0 a 127: 0 conserva el origen y 127 aplica por completo el cambio elegido.

Los cálculos se realizan fuera de NMI. NMI realiza la transferencia de los colores resultantes.

=== Efecto global ===

{| class="wikitable"
! Variable !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selecciona el efecto global. El valor 0 permite restaurar los colores de base.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 0-7 que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 8-F que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Guarda el último ID global procesado por cada paleta.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controla la participación del color fijo y el color 0,0.
|}

Para cada paleta habilitada, el administrador:

# Comprueba si necesita actualizar el resultado del efecto.
# Prepara la base RGB o HSL si todavía falta.
# Calcula el efecto si el resultado anterior ya no sirve.
# Prepara los colores en formato SNES y solicita su transferencia.
# Confirma el ID procesado cuando la carga correspondiente se acepta.

Si se mantiene el mismo efecto y no cambió la base, no hace falta calcularlo otra vez. Al cambiar el ID global se invalidan los resultados anteriores, no necesariamente las bases RGB y HSL.

El ID global 0 también requiere una actualización: el sistema debe cargar de nuevo los colores de base para quitar el efecto anterior.

=== Efecto local y concatenación ===

Un recurso puede tener un efecto propio y recibir también el global. Por ejemplo, un sprite puede cambiar de tono y después oscurecerse junto con el nivel.

El orden es:

# Preparar el resultado del efecto local.
# Utilizarlo como base para el efecto global mediante la llamada de concatenación.
# Calcular el efecto global sobre esa base.
# Cargar el resultado combinado, sin mostrar antes la versión que solo tiene el efecto local.

* La concatenación RGB se utiliza con efectos RGB.
* La concatenación HSL se utiliza con efectos HSL.
* Los recursos que comparten un destino de CGRAM comparten sus colores. Para mostrar dos efectos locales distintos, necesitan destinos que permitan mantener ambos resultados.

=== Si no se acepta la transferencia ===

* Calcular el efecto no significa que ya esté en CGRAM.
* Si la transferencia no se acepta, el administrador puede volver a intentar la actualización.
* Cuando corresponde, se mantiene el resultado anterior utilizable hasta poder sustituirlo.
* No se deben cargar primero los colores originales sin efecto: podrían verse así durante un frame antes del resultado correcto.

== Cómo trabajan juntos ==

El recorrido de un sprite dinámico reúne estas tareas:

# Su lógica elige la pose y la versión de paleta.
# La asignación busca una paleta utilizable y prepara los colores si hace falta.
# La caché protege la pose ya cargada o prepara la carga de una nueva.
# El dibujo escribe los datos de sus piezas en los buffers OAM.
# El administrador de efectos prepara los cambios globales pendientes.
# NMI realiza las transferencias de gráficos y colores solicitadas.

Compartir gráficos, compartir una paleta y compartir una rutina de dibujo son tres cosas distintas. Dynamic Xtreme puede aprovechar cada una sin obligar a que los recursos compartan también las demás.

es/Dynamic Xtreme UberASM guide

2026-10-25T18:00:23Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_UberASM_guide}}

En este artículo se explica cómo utilizar Dynamic Xtreme desde UberASM para configurar los recursos de un nivel y crear cambios de gráficos y colores durante el juego. Se incluyen ejemplos para reservar paletas, elegir el espacio disponible para sprites dinámicos, crear animaciones y modificar los gráficos del jugador.

== Requisitos ==

* Tener UberASMTool instalado y configurado para insertar códigos en tu ROM.
* Tener Dynamic Xtreme instalado con las funciones necesarias para el ejemplo que quieras utilizar. Consulta la [[es/Dynamic_Xtreme_Quick_Start|guía de inicio rápido]] para su instalación.

Para consultar los parámetros de una llamada o el uso de una variable, utiliza la [[es/Dynamic_Xtreme_ASM_API|referencia de la API ASM]].

Estas son las funcionalidades necesarias para cada ejemplo:

{| class="wikitable"
! Ejemplo !! Funcionalidades que debes habilitar
|-
| [[#Reservar paletas para otros recursos|Reservar paletas para otros recursos]]
| <code>PalettesChange</code>.
|-
| [[#Elegir el espacio de VRAM para sprites dinámicos|Elegir el espacio de VRAM para sprites dinámicos]]
| <code>GraphicsChange</code> y <code>DynamicPoses</code>. Para dibujar esas poses con Dynamic Xtreme también necesitas <code>DrawingSystem</code>.
|-
| [[#Configurar la cantidad de datos que se transfieren por frame|Configurar la cantidad de datos que se transfieren por frame]]
| <code>GraphicsChange</code> para las cargas gráficas o <code>PalettesChange</code> para las cargas de paletas; ambas si utilizas los dos tipos de carga.
|-
| [[#Crear animaciones de gráficos|Crear animaciones de gráficos]]
| <code>GraphicsChange</code> y <code>PalettesChange</code>, porque el ejemplo carga gráficos y una paleta. Añade <code>PalettesEffects</code> si cambias <code>!PaletteGlobalEffect</code> a 1 para utilizar el efecto global.
|-
| [[#Cambiar paletas durante el juego|Cambiar paletas durante el juego]]
| <code>PalettesChange</code> y, con <code>!PaletteGlobalEffect = 1</code> como en el ejemplo, <code>PalettesEffects</code>. Para cargar sin efecto global, utiliza <code>!PaletteGlobalEffect = 0</code>; en ese caso basta con <code>PalettesChange</code>.
|-
| [[#Cambiar los gráficos del jugador|Cambiar los gráficos del jugador]]
| <code>PlayerFeatures</code>, junto con sus dependencias <code>GraphicsChange</code> y <code>PalettesChange</code>.
|-
| [[#Aplicar un efecto global de paleta|Aplicar un efecto global de paleta]], fijo, cíclico o de transición
| <code>PalettesChange</code> y <code>PalettesEffects</code>.
|}

La animación de gráficos de esta guía copia datos a un destino fijo de VRAM: no necesita <code>DynamicPoses</code> ni <code>DrawingSystem</code>. Para conocer las rutinas y macros que habilita cada funcionalidad, consulta la [[es/Dynamic_Xtreme_ASM_API#Funcionalidades necesarias para utilizar la API|tabla de funcionalidades de la API]].

== Preparar los ejemplos ==

Cada ejemplo es independiente. Guarda el código de nivel en la carpeta correspondiente de UberASMTool y añádelo a su lista. Si reúnes varios ejemplos en un archivo, combina sus bloques <code>load</code>, <code>init</code> y <code>main</code> para no repetir las mismas etiquetas.

* <code>load</code> prepara datos durante la carga del nivel.
* <code>init</code> prepara las opciones al entrar al nivel. El ejemplo de reserva de paletas utiliza este bloque.
* <code>main</code> ejecuta el código durante el juego, una vez por frame.

Los defines y macros de Dynamic Xtreme deben estar disponibles en UberASMTool mediante la integración realizada durante la instalación. Si utilizas gráficos, paletas o efectos adicionales, decláralos en el ASM mediante los includes correspondientes:

<pre>
;#incdyn "DynamicXtreme/MyResources.dynamicinfo"
;#incpale "DynamicXtreme/MyEffect.paleffect"
</pre>

Las rutas son relativas al ASM. Incluye únicamente los archivos que utiliza tu ejemplo. También puedes usar las carpetas tradicionales de Dynamic Xtreme, como se explica en [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos]].

Después de añadir o modificar estos recursos, instala primero Dynamic Xtreme y después UberASMTool. Si solo cambias la lógica del ASM, basta con volver a ejecutar UberASMTool.

Los nombres <code>RAM_LIBRE_...</code> de los ejemplos son marcadores: reemplázalos por direcciones de RAM libre antes de insertar el código. No son defines de Dynamic Xtreme. Reserva la cantidad de bytes indicada y utiliza direcciones distintas para variables que deban coexistir. Comprueba que no las utilicen el juego, Dynamic Xtreme, Lunar Magic u otros recursos; que una dirección esté libre en SMW original no garantiza que siga libre en tu ROM. Puedes buscar direcciones en el [https://www.smwcentral.net/?p=memorymap&game=smw&u=0&address=&sizeOperation=%3D&sizeValue=&region%5B%5D=ram&type=Empty&description= mapa de RAM de SMW Central filtrado por espacios vacíos].

Si utilizas una dirección corta de RAM de SMW que no pertenece a la '''Direct Page''', añade <code>|!addr</code> para aplicar el remapeo correspondiente a LoROM o SA-1. Por ejemplo, al elegir la dirección del temporizador:

<pre>
!AnimationTimer = RAM_LIBRE_ANIM_TIMER|!addr
</pre>

Sustituye <code>RAM_LIBRE_ANIM_TIMER</code> por la dirección elegida y conserva <code>|!addr</code>. Las direcciones de Direct Page se acceden mediante la base D del contexto de ejecución y no utilizan este remapeo. Si eliges una dirección completa de 24 bits, comprueba su banco y que las instrucciones del ejemplo puedan acceder a ella; <code>|!addr</code> está pensado aquí para las direcciones cortas fuera de Direct Page.

== Reservar paletas para otros recursos ==

Si una animación, un HUD u otro recurso necesita una paleta fija, conviene reservarla para que Dynamic Xtreme no la elija al asignar colores a los sprites dinámicos.

Para reservarla, escribe <code>$FFFE</code> en su entrada de <code>DX_Dynamic_Palettes_ID</code>. Cada entrada ocupa 2 bytes. Por ejemplo, la paleta 9 utiliza el desplazamiento <code>$12</code>: 9 × 2.

Consulta el significado de esta tabla en [[es/Dynamic_Xtreme_ASM_API#Paletas y efecto global|Paletas y efecto global de la API]].

<pre>
init:
REP #$20
LDA #$FFFE
STA.l DX_Dynamic_Palettes_ID+$12 ; Reservar la paleta 9
SEP #$20
RTL
</pre>

Para reservar varias, escribe el mismo valor en sus entradas:

{| class="wikitable"
! Paleta !! Desplazamiento
|-
| 8 || <code>$10</code>
|-
| 9 || <code>$12</code>
|-
| A || <code>$14</code>
|-
| B || <code>$16</code>
|-
| C || <code>$18</code>
|-
| D || <code>$1A</code>
|-
| E || <code>$1C</code>
|-
| F || <code>$1E</code>
|}

La reserva impide que la asignación automática reclame esa paleta; no carga colores por sí misma. Un recurso configurado para utilizarla manualmente todavía puede cambiar sus colores, por lo que no debes asignársela también a otro recurso que necesite una paleta diferente.

== Elegir el espacio de VRAM para sprites dinámicos ==

Los sprites dinámicos necesitan una parte de VRAM donde cargar sus poses. Elige un espacio que no estés utilizando para gráficos fijos del nivel.

Puedes consultar el [[SMW_VRAM_Map#Levels|mapa de VRAM de SMW en SNESLab]] para ver qué regiones corresponden a SP1, SP2, SP3 y SP4.

Por ejemplo, para permitir que utilicen SP4:

La rutina [[es/Dynamic_Xtreme_ASM_API#DynamicPoseSpaceConfig|DynamicPoseSpaceConfig]] recibe una de las configuraciones predefinidas.

<pre>
init:
LDA #!DynamicSpaceConfigSP4
JSL !DynamicPoseSpaceConfig
RTL
</pre>

Si necesitas más espacio y el nivel lo permite, puedes elegir <code>!DynamicSpaceConfigSP34</code> para SP3 y SP4, o <code>!DynamicSpaceConfigSP234</code> para SP2, SP3 y SP4. Hay más opciones, incluidas medias páginas y configuraciones para compartir espacio con el jugador o DSX.

Los defines disponibles están en <code>DXDefines.asm</code> y en la [[es/Dynamic_Xtreme_ASM_API#Configuraciones_de_espacio_para_poses_dinámicas|tabla de configuraciones de la API]]. Configura el espacio antes de que el nivel empiece a cargar poses; cambiarlo no elimina automáticamente las poses que ya estaban en VRAM.

=== Crear una configuración propia ===

Si necesitas combinar espacios de otra manera, utiliza [[es/Dynamic_Xtreme_ASM_API#DefineDynamicSpaceConfig|DefineDynamicSpaceConfig]]. Este ejemplo deja disponible la primera mitad de SP3 y todo SP4, y restringe el resto:

<pre>
init:
; SP1 y SP2 restringidos.
%DefineDynamicSpaceConfig($00, $3F, $80)

; Primera mitad de SP3 disponible.
%DefineDynamicSpaceConfig($40, $4F, $00)

; Segunda mitad de SP3 restringida.
%DefineDynamicSpaceConfig($50, $5F, $80)

; SP4 disponible.
%DefineDynamicSpaceConfig($60, $7F, $00)
RTL
</pre>

Los dos primeros parámetros son el primer y el último bloque de 16×16, incluidos ambos. El tercero utiliza <code>$00</code> para permitir poses dinámicas o <code>$80</code> para restringir el espacio. Los IDs avanzan de izquierda a derecha y de arriba abajo, con 8 bloques por fila. La [[es/Dynamic_Xtreme_ASM_API#DefineDynamicSpaceConfig|documentación de la macro]] incluye la tabla de numeración completa.

Este ejemplo sustituye la llamada a la configuración predefinida: no ejecutes las dos configuraciones una después de otra. Ajusta los rangos para cubrir los bloques <code>$00–$7F</code> sin superponerlos y restringe las zonas que necesiten conservar otros gráficos del nivel. Requiere <code>GraphicsChange</code> y <code>DynamicPoses</code>, igual que el ejemplo anterior.

== Configurar la cantidad de datos que se transfieren por frame ==

<code>DX_Dynamic_MaxDataPerFrame</code> indica cuántos bytes pueden programar las cargas normales de Dynamic Xtreme durante un frame. Lo comparten las poses dinámicas, las animaciones y las demás transferencias realizadas con sus macros.

Consulta estas variables en [[es/Dynamic_Xtreme_ASM_API#Contadores y cantidad de datos por frame|Contadores y cantidad de datos por frame de la API]].

El valor predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Este ejemplo lo aumenta a <code>$0A00</code>, equivalente a 2560 bytes:

<pre>
init:
REP #$20
LDA #$0A00
STA.l DX_Dynamic_MaxDataPerFrame
SEP #$20
RTL
</pre>

Subirlo permite intentar más cargas durante el mismo frame, pero no aumenta el tiempo que tiene SNES para copiarlas. Si la cantidad total es excesiva, pueden aparecer problemas visuales. Ajusta el valor según el nivel y comprueba el resultado con sus sprites y animaciones funcionando juntos.

Las macros normales devuelven el carry desactivado si una carga no cabe en el límite. En ese caso, conserva lo que ya se muestra y vuelve a intentarlo después. Las variantes <code>Forced</code> se saltan la comprobación y también suman sus bytes al total.

== Crear animaciones de gráficos ==

Este ejemplo crea una animación de gráficos: una tabla indica dónde empieza cada imagen, un temporizador controla cuándo cambiarla y la imagen anterior se mantiene si no se acepta la transferencia.

Utiliza [[es/Dynamic_Xtreme_ASM_API#TransferToVRAM|TransferToVRAM]] para los cambios de gráficos, su [[es/Dynamic_Xtreme_ASM_API#Variantes Forced|variante Forced]] para la carga inicial y [[es/Dynamic_Xtreme_ASM_API#TransferPaletteResource|TransferPaletteResource]] para los colores. Consulta esos enlaces para sus parámetros, registros y resultados.

Declara los archivos del ejemplo en <code>DynamicXtreme/SMMArrow.dynamicinfo</code>:

<pre>
Resources:
SMMArrow.bin
Palettes:
SMMArrowPal.bin
</pre>

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incdyn "DynamicXtreme/SMMArrow.dynamicinfo"

; Aquí pon RAM libre: un byte distinto para cada variable.
!CurrentPoseIndex = RAM_LIBRE_ANIM_POSE
!AnimationTimer = RAM_LIBRE_ANIM_TIMER
!PaletteLoaded = RAM_LIBRE_ANIM_PALETA

; Frames de espera antes de intentar el siguiente cambio.
!TimePerPose = $03

; Bytes de cada imagen: un tile de 8x8 en 4bpp ocupa $0020.
!DataSend = $0200

; Cantidad de imágenes utilizadas.
!NumberOfPoses = $05

; Origen: recurso instalado. También puedes usar !AN2Buffer2.
!Source = !ResourceSMMArrow

; Dirección de destino en VRAM.
!Destination = !BG2Line0

; Paleta instalada y primer color de destino.
!Palette = "SMMArrowPal"
!PaletteDestination = $71

; 0 = sin efecto global; 1 = recibe el efecto global.
!PaletteGlobalEffect = 0

init:
STZ !CurrentPoseIndex
LDA #!TimePerPose
STA !AnimationTimer
STZ !PaletteLoaded

%ForcedTransferToVRAM(#!Destination, #!Source, #((!Source>>16)&$FF), #!DataSend)
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCC .Return
LDA #$01
STA !PaletteLoaded
.Return
RTL

main:
; Reintentar la paleta si no se aceptó durante init.
LDA !PaletteLoaded
BNE .Animate
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCS .PaletteReady
RTL
.PaletteReady
LDA #$01
STA !PaletteLoaded

.Animate
LDA !AnimationTimer
BEQ .NextPose
DEC !AnimationTimer
RTL

.NextPose
LDA !CurrentPoseIndex
INC A
CMP #!NumberOfPoses
BCC .SelectPose
LDA #$00
.SelectPose
STA $05
ASL
TAX

REP #$20
LDA.l PosesTable,x
CLC
ADC.w #!Source
STA $00
SEP #$20

%TransferToVRAM(#!Destination, $00, #((!Source>>16)&$FF), #!DataSend)
BCC .Return

LDA $05
STA !CurrentPoseIndex
LDA #!TimePerPose
STA !AnimationTimer
.Return
RTL

PosesTable:
dw $0000
dw !DataSend*$01
dw !DataSend*$02
dw !DataSend*$03
dw !DataSend*$04
</pre>

'''Qué puedes cambiar'''

* <code>!TimePerPose</code>: tiempo de espera. Con <code>$03</code>, el cambio se intenta cada cuatro frames: tres para descontar el temporizador y uno para realizar el cambio.
* <code>!DataSend</code>: bytes de cada imagen. <code>$0200</code> equivale a 16 tiles de 8×8 en 4bpp.
* <code>!NumberOfPoses</code> y <code>PosesTable</code>: cantidad de imágenes y sus desplazamientos dentro del origen. El ejemplo utiliza las primeras cinco imágenes de <code>SMMArrow.bin</code>. Si añades más, amplía también la tabla.
* <code>!Source</code>: dirección de los gráficos. El ejemplo lee directamente <code>!ResourceSMMArrow</code>; para animar gráficos ya preparados por Lunar Magic puedes usar <code>!AN2Buffer2</code>.
* <code>!Destination</code>: zona de VRAM que se actualizará. Coloca en el nivel tiles que utilicen esa zona y comprueba que otro recurso no la sobrescriba.
* <code>!Palette</code>, <code>!PaletteDestination</code> y <code>!PaletteGlobalEffect</code>: paleta, primer color de destino y participación en el efecto global.

Reemplaza los tres marcadores de RAM del principio por direcciones disponibles durante todo el nivel: cada variable necesita un byte propio. No son scratch temporales. <code>!PaletteLoaded</code> permite reintentar una carga de paleta rechazada sin repetirla después de que haya sido aceptada.

<code>!ResourceSMMArrow</code>, <code>!PaletteSMMArrowPal</code> y <code>!PaletteSMMArrowPalSize</code> se generan al instalar el DynamicInfo y quedan en <code>DXDefines.asm</code>. Sus nombres se normalizan en PascalCase eliminando separadores; en este caso se conservan las mayúsculas de <code>SMMArrow</code> y <code>SMMArrowPal</code>.

Todas las imágenes utilizadas deben quedar en el mismo banco del origen. La carga inicial de gráficos utiliza <code>Forced</code>; los siguientes cambios respetan el límite de datos por frame. Si una carga se rechaza, el código conserva la imagen anterior y vuelve a intentarla en el siguiente frame, sin avanzar el índice ni reiniciar el temporizador.

El temporizador avanza cada vez que se ejecuta <code>main</code>. Si quieres detener la animación durante la pausa o cuando se congela la acción, puedes comprobar <code>$13D4|!addr</code> y <code>$9D</code> antes de descontarlo.

== Cambiar paletas durante el juego ==

Las macros <code>TransferPalette</code> permiten cargar colores y mantener actualizadas las copias que utilizan SMW y Dynamic Xtreme. También se encargan de preparar los efectos de paleta, por lo que no necesitas copiar buffers ni borrar indicadores a mano.

Este ejemplo utiliza [[es/Dynamic_Xtreme_ASM_API#TransferPaletteResource|TransferPaletteResource]]; consulta su entrada en la API para los parámetros y el significado del carry.

El ejemplo utiliza <code>SMMArrowPal.bin</code>, un archivo de 15 colores (<code>$001E</code> bytes), y cambia los colores 1-F de la paleta 7. El color 0 queda sin modificar.

En <code>DynamicXtreme/SMMArrow.dynamicinfo</code>, declara los gráficos como recurso general y la paleta en <code>Palettes</code>:

<pre>
Resources:
SMMArrow.bin
Palettes:
SMMArrowPal.bin
</pre>

En el ASM del nivel:

<pre>
;#incdyn "DynamicXtreme/SMMArrow.dynamicinfo"

; Aquí pon una RAM libre de un byte.
!PaletteChangePending = RAM_LIBRE_CAMBIO_PALETA

!Palette = "SMMArrowPal"
!PaletteDestination = $71
!PaletteGlobalEffect = 1

init:
LDA #$01
STA !PaletteChangePending
; Continuar con el primer intento de carga.

main:
LDA !PaletteChangePending
BNE .TryTransfer
RTL

.TryTransfer
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCC .Return

; Confirmar el cambio solo si la llamada fue aceptada.
STZ !PaletteChangePending
.Return
RTL
</pre>

Reemplaza <code>RAM_LIBRE_CAMBIO_PALETA</code> por una dirección de RAM libre de un byte, disponible durante todo el nivel. <code>!PaletteChangePending</code> se pone en 1 al solicitar el cambio y solo vuelve a 0 cuando la macro devuelve el carry activado. Si la llamada falla, el cambio queda pendiente y se reintenta en el siguiente frame. Una vez aceptado, no se repite la carga.

<code>!Palette</code> selecciona el recurso y <code>!PaletteDestination</code> el primer color de destino. <code>!PaletteGlobalEffect</code>, utilizado como último parámetro de la macro, elige cómo se carga:

* <code>1</code>: prepara los colores originales para que reciban el efecto global antes de mostrarse. También deja la paleta preparada si todavía no has seleccionado un efecto.
* <code>0</code>: carga los colores sin efecto global y excluye esa paleta del efecto. Además actualiza los buffers de SMW, necesarios para evitar problemas de colores durante la animación de victoria del goal.

Para cargar la misma paleta sin efecto global, cambia únicamente este define; conserva la comprobación del carry:

<pre>
!PaletteGlobalEffect = 0
</pre>

Si los efectos están deshabilitados en la instalación, ambas opciones realizan una carga directa. Cuando están habilitados y utilizas <code>1</code>, el sistema carga el resultado ya procesado; no se muestra primero la paleta sin efecto durante un frame.

<code>SMMArrowPal</code> utiliza los defines <code>!PaletteSMMArrowPal</code> y <code>!PaletteSMMArrowPalSize</code>, generados desde <code>Palettes</code> del DynamicInfo y publicados en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores y poniendo en mayúscula la inicial de cada palabra. En este caso se conserva <code>SMMArrowPal</code> tal como está escrito.

Para solicitar de nuevo el cambio durante el juego, pon <code>!PaletteChangePending</code> en 1 cuando se cumpla la condición que elijas. No lo hagas cada frame si la paleta no cambia. En una carga directa, el carry activado indica que se programó la transferencia; con efecto global, indica que los colores originales quedaron preparados, no que el resultado ya esté en pantalla.

La opción de efecto se aplica a toda la paleta de 16 colores. Si cargas colores para recibir un efecto global, prepara todos sus colores visibles, como los 15 de este ejemplo; no cambies solo unos pocos esperando conservar una base que todavía no has preparado.

Si eliges una paleta de sprites 8-F para un uso fijo, resérvala primero como se explica al comienzo del artículo. Estas macros no realizan asignación automática. Para cargar desde una dirección, un puntero o una tabla, consulta [[es/Dynamic_Xtreme_ASM_API#Cargar_colores_con_TransferPalette|Cargar colores con TransferPalette en la API]].

== Cambiar los gráficos del jugador ==

Este ejemplo alterna entre el jugador original y Geno al pulsar arriba. Sus defines permiten elegir los gráficos y las cuatro paletas: Mario, Luigi, Mario con fuego y Luigi con fuego. También vuelve a seleccionar la paleta cuando cambia el estado del jugador.

Necesita <code>PlayerFeatures</code> habilitado. Los gráficos personalizados deben utilizar la misma organización de poses que los originales; cambiar el origen no adapta un spritesheet de otro formato.

El código utiliza las [[es/Dynamic_Xtreme_ASM_API#Jugador y Yoshi|variables del jugador]] y las macros [[es/Dynamic_Xtreme_ASM_API#Div y DivW|DivW]], [[es/Dynamic_Xtreme_ASM_API#TransferPaletteFromPointer|TransferPaletteFromPointer]] y [[es/Dynamic_Xtreme_ASM_API#TransferPaletteFromAddress|TransferPaletteFromAddress]]. Sus entradas de la API explican los parámetros, registros y resultados de cada llamada.

En <code>DynamicXtreme/Geno.dynamicinfo</code>, declara:

<pre>
Resources:
Geno.bin
Palettes:
GenoPal.bin
GenoPalPlayer2.bin
FireGenoPal.bin
FireGenoPalPlayer2.bin
</pre>

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incdyn "DynamicXtreme/Geno.dynamicinfo"

; Aquí pon una RAM libre de dos bytes consecutivos.
!Last0D82 = RAM_LIBRE_JUGADOR_2_BYTES

; Gráficos del jugador personalizado.
!PlayerGFXResource = !ResourceGeno

; Paletas: jugador 1, jugador 2 y sus variantes con fuego.
!PlayerGFXPalette = !PaletteGenoPal
!PlayerGFXPalettePlayer2 = !PaletteGenoPalPlayer2
!PlayerGFXFirePalette = !PaletteFireGenoPal
!PlayerGFXFirePalettePlayer2 = !PaletteFireGenoPalPlayer2

; Botón de cambio: $08 = arriba.
!ChangeButton = $08

init:
REP #$20
LDA $0D82|!addr
STA !Last0D82
SEP #$20

main:
LDA !ButtonDown_BYETUDLR
AND #!ChangeButton
BNE .Change

REP #$20
LDA $0D82|!addr
CMP !Last0D82
BNE .Reload
SEP #$20
RTL

.Change
LDA.l DX_Dynamic_Player_GFX_BNK
CMP.b #!GFX32Buffer>>16
BEQ .ChooseGeno
JMP .Mario
.ChooseGeno
JMP .Geno

.Reload
SEP #$20
LDA.l DX_Dynamic_Player_GFX_BNK
CMP.b #!GFX32Buffer>>16
BNE .Geno
JMP .Mario

.Geno
; Obtener 0, 1, 2 o 3 según jugador y estado de fuego.
REP #$20
LDA $0D82|!addr
SEC
SBC #!PlayerBasePalette
STA $00
SEP #$20
%DivW($01, $00, #$14)

; Cada dirección de GenoPals ocupa tres bytes.
LDA !DivisionResult
ASL
CLC
ADC !DivisionResult
TAX

; Conservar el origen elegido y preparar los colores 2-5.
REP #$20
LDA.l GenoPals,x
STA $03
CLC
ADC #$0002
STA $00
SEP #$20
LDA.l GenoPals+2,x
STA $02
STA $05

%TransferPaletteFromPointer($00, #$82, $0008, 0)
BCS .ApplyGeno
RTL

.ApplyGeno
REP #$20
LDA.w #!PlayerGFXResource
STA.l DX_Dynamic_Player_GFX_Addr
LDA.w #(!PlayerGFXResource>>16)&$00FF
STA.l DX_Dynamic_Player_GFX_BNK

; La rutina del jugador carga los colores 6-F.
LDA $03
CLC
ADC #$000A
STA.l DX_Dynamic_Player_Palette_Addr
SEP #$20
LDA $05
STA.l DX_Dynamic_Player_Palette_BNK
JMP .ConfirmSelection

.Mario
%TransferPaletteFromAddress(!PlayerPaletteColor2To5, #$82, $0008, 0)
BCS .ApplyMario
RTL

.ApplyMario
REP #$20
LDA.w #!GFX32Buffer
STA.l DX_Dynamic_Player_GFX_Addr
LDA $0D82|!addr
STA.l DX_Dynamic_Player_Palette_Addr
LDA.w #(!GFX32Buffer>>16)&$00FF
STA.l DX_Dynamic_Player_GFX_BNK
LDA #$0000
STA.l DX_Dynamic_Player_Palette_BNK
SEP #$20

.ConfirmSelection
REP #$20
LDA $0D82|!addr
STA !Last0D82
SEP #$20
RTL

GenoPals:
dl !PlayerGFXPalette
dl !PlayerGFXPalettePlayer2
dl !PlayerGFXFirePalette
dl !PlayerGFXFirePalettePlayer2
</pre>

'''Qué puedes cambiar'''

* <code>!PlayerGFXResource</code>: gráficos del personaje personalizado.
* Los cuatro defines <code>!PlayerGFX...Palette...</code>: direcciones de sus paletas, en el orden de la tabla <code>GenoPals</code>.
* <code>!ChangeButton</code>: botón que alterna entre los personajes. Utiliza los bits del control <code>BYETUDLR</code>; <code>$08</code> corresponde a arriba.
* <code>!Last0D82</code>: reemplaza <code>RAM_LIBRE_JUGADOR_2_BYTES</code> por una dirección de RAM libre con dos bytes consecutivos disponibles. Guarda la selección de paleta del juego; ninguno de esos bytes debe estar ocupado por otro código.

<code>!ResourceGeno</code> y los defines <code>!PaletteGenoPal</code>, <code>!PaletteGenoPalPlayer2</code>, <code>!PaletteFireGenoPal</code> y <code>!PaletteFireGenoPalPlayer2</code> se generan desde el DynamicInfo y quedan en <code>DXDefines.asm</code>. Los nombres usan PascalCase eliminando espacios, guiones y guiones bajos, y conservando las mayúsculas ya presentes.

Cada archivo de paleta contiene los colores 1-F. Se omite su primer color para copiar los colores 2-5; los últimos diez comienzan en <code>+$0A</code> y los utiliza la rutina del jugador.

Las cargas de los colores 2-5 utilizan <code>TransferPalette</code>, que también actualiza los buffers de SMW. El ejemplo no confirma el cambio de gráficos si esa transferencia es rechazada. Un cambio pendiente por el estado del jugador se vuelve a intentar mientras no coincida con <code>!Last0D82</code>; si se rechaza un cambio solicitado con el botón, vuelve a pulsarlo.

El código distingue al jugador original por el banco de <code>!GFX32Buffer</code>. Si lo adaptas para alternar entre varios personajes personalizados en ROM, necesitarás otra forma de recordar cuál está seleccionado.

Este ejemplo carga la paleta del jugador sin efecto global. No basta con cambiar a <code>1</code> el parámetro de una carga de cuatro colores para añadirle un efecto: en ese caso hay que preparar todos los colores visibles de la paleta 8 y respetar su carga especial.

== Aplicar un efecto global de paleta ==

Los siguientes ejemplos permiten aplicar un efecto fijo, recorrer efectos en un ciclo o realizar una transición que se detiene al terminar. Puedes elegir cada paleta por separado e incluir el color fijo. Los códigos de ciclo y transición también permiten configurar la velocidad con <code>!Delay</code>.

Los tres configuran las [[es/Dynamic_Xtreme_ASM_API#Paletas y efecto global|variables del efecto global]] y las de [[es/Dynamic_Xtreme_ASM_API#Color fijo y primer color de la paleta|color fijo y primer color de la paleta]]. Consulta sus entradas en la API para el significado de cada variable.

En los archivos <code>*.paleffect</code>, <code>EffectType</code> selecciona el tipo de efecto. Los ratios utilizan valores de 0 a 127 y los valores <code>Channel</code>, de 0 a 31.

=== Elegir las paletas afectadas ===

En cada código, cambia <code>!P0</code> a <code>!PF</code> a 1 para incluir la paleta correspondiente o a 0 para excluirla. <code>!EnableFixedColor</code> controla el color fijo y <code>!EnableColor00</code> permite incluir también el color 0,0.

Las máscaras <code>!EnableBG</code>, <code>!EnableSP</code> y <code>!EnableColors</code> se calculan a partir de esos ajustes. No necesitas modificarlas a mano. En la API actual, el bit bajo corresponde a la primera paleta de cada grupo:

{| class="wikitable"
! Valor del bit !! Paleta de fondo !! Paleta de sprites
|-
| <code>$01</code> || 0 || 8
|-
| <code>$02</code> || 1 || 9
|-
| <code>$04</code> || 2 || A
|-
| <code>$08</code> || 3 || B
|-
| <code>$10</code> || 4 || C
|-
| <code>$20</code> || 5 || D
|-
| <code>$40</code> || 6 || E
|-
| <code>$80</code> || 7 || F
|}

El color fijo y el color 0,0 utilizan <code>DX_PPU_ColorEffect_Enable</code>: bit <code>$01</code> y bit <code>$02</code>, respectivamente.

En sprites con asignación dinámica, configura también el bit E de <code>PaletteOption</code>. Si cargas paletas mediante <code>TransferPalette</code>, su último parámetro determina si esas paletas participan en el efecto global. Evita que otro código vuelva a escribir máscaras distintas sin tener en cuenta esa configuración.

=== Aplicar un efecto fijo ===

Este ejemplo aplica el efecto que indiques en <code>!PaletteEffetID</code>. La configuración mostrada habilita todas las paletas y el color fijo, y selecciona el último efecto de <code>DecreaseSaturation</code>.

Guarda el siguiente contenido en <code>DynamicXtreme/DecreaseSaturation.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel2": 0, "Ratio2": 4, "EffectType": 11},
{"Channel2": 0, "Ratio2": 8, "EffectType": 11},
{"Channel2": 0, "Ratio2": 12, "EffectType": 11},
{"Channel2": 0, "Ratio2": 16, "EffectType": 11},
{"Channel2": 0, "Ratio2": 20, "EffectType": 11},
{"Channel2": 0, "Ratio2": 25, "EffectType": 11},
{"Channel2": 0, "Ratio2": 29, "EffectType": 11},
{"Channel2": 0, "Ratio2": 33, "EffectType": 11},
{"Channel2": 0, "Ratio2": 37, "EffectType": 11},
{"Channel2": 0, "Ratio2": 41, "EffectType": 11},
{"Channel2": 0, "Ratio2": 45, "EffectType": 11},
{"Channel2": 0, "Ratio2": 49, "EffectType": 11},
{"Channel2": 0, "Ratio2": 53, "EffectType": 11},
{"Channel2": 0, "Ratio2": 57, "EffectType": 11},
{"Channel2": 0, "Ratio2": 61, "EffectType": 11},
{"Channel2": 0, "Ratio2": 66, "EffectType": 11},
{"Channel2": 0, "Ratio2": 70, "EffectType": 11},
{"Channel2": 0, "Ratio2": 74, "EffectType": 11},
{"Channel2": 0, "Ratio2": 78, "EffectType": 11},
{"Channel2": 0, "Ratio2": 82, "EffectType": 11},
{"Channel2": 0, "Ratio2": 86, "EffectType": 11},
{"Channel2": 0, "Ratio2": 90, "EffectType": 11},
{"Channel2": 0, "Ratio2": 94, "EffectType": 11},
{"Channel2": 0, "Ratio2": 98, "EffectType": 11},
{"Channel2": 0, "Ratio2": 102, "EffectType": 11},
{"Channel2": 0, "Ratio2": 107, "EffectType": 11},
{"Channel2": 0, "Ratio2": 111, "EffectType": 11},
{"Channel2": 0, "Ratio2": 115, "EffectType": 11},
{"Channel2": 0, "Ratio2": 119, "EffectType": 11},
{"Channel2": 0, "Ratio2": 123, "EffectType": 11},
{"Channel2": 0, "Ratio2": 127, "EffectType": 11},
{"Channel2": 0, "Ratio2": 127, "EffectType": 11}
]
}
</pre>

El archivo define 32 efectos. <code>EffectType = 11</code> corresponde a <code>MixS</code>; <code>Channel2 = 0</code> indica que se reduce la saturación y <code>Ratio2</code> controla cuánto. El último efecto utiliza 127, que aplica el cambio completo.

El código ASM es:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/DecreaseSaturation.paleffect"

; 1 = incluir la paleta en el efecto; 0 = excluirla.
!P0 = 1
!P1 = 1
!P2 = 1
!P3 = 1
!P4 = 1
!P5 = 1
!P6 = 1
!P7 = 1

!P8 = 1
!P9 = 1
!PA = 1
!PB = 1
!PC = 1
!PD = 1
!PE = 1
!PF = 1

!EnableFixedColor = 1
!EnableColor00 = 0

; Efecto que se aplica al entrar al nivel.
!PaletteEffetID = !PaletteEffectIDDecreaseSaturation31

; Máscaras calculadas: no hace falta modificarlas.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!PaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL
</pre>

'''Qué puedes cambiar'''

* <code>!P0</code> a <code>!PF</code>: paletas afectadas.
* <code>!EnableFixedColor</code> y <code>!EnableColor00</code>: participación de esos colores.
* <code>!PaletteEffetID</code>: efecto seleccionado. Puedes utilizar cualquier ID generado desde tu archivo de efectos, no solo el último de este ejemplo.

Los defines <code>!PaletteEffectIDDecreaseSaturation0</code> a <code>!PaletteEffectIDDecreaseSaturation31</code> se generan desde el <code>*.paleffect</code> y quedan en <code>DXDefines.asm</code>. El nombre usa PascalCase eliminando espacios, guiones y guiones bajos, y conservando las mayúsculas ya presentes.

La selección se realiza en <code>init</code>; no hace falta repetirla cada frame. Para quitar el efecto, escribe 0 en el ID global y deja las paletas habilitadas para que el sistema restaure sus colores originales:

<pre>
REP #$20
LDA #$0000
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
</pre>

=== Hacer que el efecto se repita en un ciclo ===

Este ejemplo recorre una secuencia de efectos y vuelve al primero. Puedes configurar la velocidad, el primer y último ID y las paletas afectadas. La configuración mostrada incluye solo la paleta 0 y el color fijo.

Guarda el siguiente contenido en <code>DynamicXtreme/Hue.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel1": 1, "Ratio1": 127, "EffectType": 9},
{"Channel1": 2, "Ratio1": 127, "EffectType": 9},
{"Channel1": 3, "Ratio1": 127, "EffectType": 9},
{"Channel1": 4, "Ratio1": 127, "EffectType": 9},
{"Channel1": 5, "Ratio1": 127, "EffectType": 9},
{"Channel1": 6, "Ratio1": 127, "EffectType": 9},
{"Channel1": 7, "Ratio1": 127, "EffectType": 9},
{"Channel1": 8, "Ratio1": 127, "EffectType": 9},
{"Channel1": 9, "Ratio1": 127, "EffectType": 9},
{"Channel1": 10, "Ratio1": 127, "EffectType": 9},
{"Channel1": 11, "Ratio1": 127, "EffectType": 9},
{"Channel1": 12, "Ratio1": 127, "EffectType": 9},
{"Channel1": 13, "Ratio1": 127, "EffectType": 9},
{"Channel1": 14, "Ratio1": 127, "EffectType": 9},
{"Channel1": 15, "Ratio1": 127, "EffectType": 9},
{"Channel1": 16, "Ratio1": 127, "EffectType": 9},
{"Channel1": 17, "Ratio1": 127, "EffectType": 9},
{"Channel1": 18, "Ratio1": 127, "EffectType": 9},
{"Channel1": 19, "Ratio1": 127, "EffectType": 9},
{"Channel1": 20, "Ratio1": 127, "EffectType": 9},
{"Channel1": 21, "Ratio1": 127, "EffectType": 9},
{"Channel1": 22, "Ratio1": 127, "EffectType": 9},
{"Channel1": 23, "Ratio1": 127, "EffectType": 9},
{"Channel1": 24, "Ratio1": 127, "EffectType": 9},
{"Channel1": 25, "Ratio1": 127, "EffectType": 9},
{"Channel1": 26, "Ratio1": 127, "EffectType": 9},
{"Channel1": 27, "Ratio1": 127, "EffectType": 9},
{"Channel1": 28, "Ratio1": 127, "EffectType": 9},
{"Channel1": 29, "Ratio1": 127, "EffectType": 9},
{"Channel1": 30, "Ratio1": 127, "EffectType": 9},
{"Channel1": 31, "Ratio1": 127, "EffectType": 9},
{"Channel1": 31, "Ratio1": 127, "EffectType": 9}
]
}
</pre>

El archivo define 32 efectos de tono. <code>EffectType = 9</code> corresponde a <code>MixH</code> y <code>Ratio1 = 127</code> aplica por completo el tono seleccionado.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/Hue.paleffect"

; 1 = incluir la paleta en el efecto; 0 = excluirla.
!P0 = 1
!P1 = 0
!P2 = 0
!P3 = 0
!P4 = 0
!P5 = 0
!P6 = 0
!P7 = 0

!P8 = 0
!P9 = 0
!PA = 0
!PB = 0
!PC = 0
!PD = 0
!PE = 0
!PF = 0

!EnableFixedColor = 1
!EnableColor00 = 0

; Valores permitidos: $00, $01, $03, $07, $0F, $1F, $3F, $7F y $FF.
!Delay = $03

!StartingPaletteEffetID = !PaletteEffectIDHue0
!EndPaletteEffetID = !PaletteEffectIDHue31

; Máscaras calculadas: no hace falta modificarlas.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!StartingPaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL

main:
LDA $14
AND #!Delay
BNE .Return

REP #$20
LDA.l DX_Dynamic_Palettes_GlobalEffectID
CMP #!EndPaletteEffetID
BCS .Restart
INC A
BRA .Store
.Restart
LDA #!StartingPaletteEffetID
.Store
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
.Return
RTL
</pre>

'''Qué puedes cambiar'''

* <code>!P0</code> a <code>!PF</code>, <code>!EnableFixedColor</code> y <code>!EnableColor00</code>: colores afectados.
* <code>!Delay</code>: separación entre cambios. <code>$00</code> cambia cada frame, <code>$01</code> cada dos, <code>$03</code> cada cuatro y <code>$07</code> cada ocho. Utiliza únicamente los valores indicados en el comentario.
* <code>!StartingPaletteEffetID</code> y <code>!EndPaletteEffetID</code>: primer y último efecto del ciclo. Deben pertenecer a una secuencia de IDs consecutivos, con el inicio menor o igual que el final.

El ciclo muestra el último ID antes de volver al primero. Utiliza <code>$14</code> para marcar el momento de los cambios; por ello, el primer intervalo depende del valor que tenga ese contador al entrar al nivel. Si quieres detenerlo al congelarse la acción, comprueba también <code>$9D</code> y <code>$13D4|!addr</code> al comienzo de <code>main</code>.

Los defines <code>!PaletteEffectIDHue0</code> a <code>!PaletteEffectIDHue31</code> se generan desde el <code>*.paleffect</code> y quedan en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores; en este caso conserva <code>Hue</code>.

=== Hacer una transición que se detiene al terminar ===

Este ejemplo avanza desde el efecto inicial hasta el final y mantiene ese último resultado. Puedes configurar las paletas afectadas, el color fijo, la velocidad y el rango de IDs.

Guarda el siguiente contenido en <code>DynamicXtreme/Night.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel1": 0, "Channel2": 0, "Ratio1": 0, "Ratio2": 0, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 4, "Ratio2": 4, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 8, "Ratio2": 8, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 12, "Ratio2": 12, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 16, "Ratio2": 16, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 20, "Ratio2": 20, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 25, "Ratio2": 25, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 29, "Ratio2": 29, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 33, "Ratio2": 33, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 37, "Ratio2": 37, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 41, "Ratio2": 41, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 45, "Ratio2": 45, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 49, "Ratio2": 49, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 53, "Ratio2": 53, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 57, "Ratio2": 57, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 61, "Ratio2": 61, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 66, "Ratio2": 66, "EffectType": 2}
]
}
</pre>

La transición tiene 17 pasos. <code>EffectType = 2</code> corresponde a <code>MixRG</code>: reduce el rojo y el verde sin modificar el azul. Los ratios aumentan de 0 a 66 para oscurecer los colores gradualmente sin eliminar por completo el rojo y el verde.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/Night.paleffect"

; 1 = incluir la paleta en el efecto; 0 = excluirla.
!P0 = 1
!P1 = 1
!P2 = 1
!P3 = 1
!P4 = 1
!P5 = 1
!P6 = 1
!P7 = 1

!P8 = 1
!P9 = 1
!PA = 1
!PB = 1
!PC = 1
!PD = 1
!PE = 1
!PF = 1

!EnableFixedColor = 1
!EnableColor00 = 0

; Valores permitidos: $00, $01, $03, $07, $0F, $1F, $3F, $7F y $FF.
!Delay = $03

!StartingPaletteEffetID = !PaletteEffectIDNight0
!EndPaletteEffetID = !PaletteEffectIDNight16

; Máscaras calculadas: no hace falta modificarlas.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!StartingPaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL

main:
LDA $14
AND #!Delay
BNE .Return

REP #$20
LDA.l DX_Dynamic_Palettes_GlobalEffectID
CMP #!EndPaletteEffetID
BCS .Finished
INC A
STA.l DX_Dynamic_Palettes_GlobalEffectID
.Finished
SEP #$20
.Return
RTL
</pre>

'''Qué puedes cambiar'''

* <code>!P0</code> a <code>!PF</code>, <code>!EnableFixedColor</code> y <code>!EnableColor00</code>: colores afectados.
* <code>!Delay</code>: tiempo entre cambios, con los mismos valores permitidos en el ejemplo de ciclo.
* <code>!StartingPaletteEffetID</code> y <code>!EndPaletteEffetID</code>: primer y último efecto. Deben ser IDs consecutivos en orden ascendente.

Los defines <code>!PaletteEffectIDNight0</code> a <code>!PaletteEffectIDNight16</code> se generan desde <code>Night.paleffect</code> y quedan en <code>DXDefines.asm</code>. Los nombres usan PascalCase eliminando separadores; aquí se conserva <code>Night</code>.

Este ejemplo cambia entre efectos de mezcla. Para una transición hacia otra paleta completa, utiliza <code>PalTransitionRGB</code> o <code>PalTransitionHSL</code>, explicados en [[es/Dynamic_Xtreme_files_and_formats#Transiciones_de_paleta|Archivos y formatos]].

es/Dynamic Xtreme UberASM guide

2026-10-25T17:56:53Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_UberASM_guide}}

En este artículo se explica cómo utilizar Dynamic Xtreme desde UberASM para configurar los recursos de un nivel y crear cambios de gráficos y colores durante el juego. Se incluyen ejemplos para reservar paletas, elegir el espacio disponible para sprites dinámicos, crear animaciones y modificar los gráficos del jugador.

== Requisitos ==

* Tener UberASMTool instalado y configurado para insertar códigos en tu ROM.
* Tener Dynamic Xtreme instalado con las funciones necesarias para el ejemplo que quieras utilizar. Consulta la [[es/Dynamic_Xtreme_Quick_Start|guía de inicio rápido]] para su instalación.

Para consultar los parámetros de una llamada o el uso de una variable, utiliza la [[es/Dynamic_Xtreme_ASM_API|referencia de la API ASM]].

Estas son las funcionalidades necesarias para cada ejemplo:

{| class="wikitable"
! Ejemplo !! Funcionalidades que debes habilitar
|-
| [[#Reservar paletas para otros recursos|Reservar paletas para otros recursos]]
| <code>PalettesChange</code>.
|-
| [[#Elegir el espacio de VRAM para sprites dinámicos|Elegir el espacio de VRAM para sprites dinámicos]]
| <code>GraphicsChange</code> y <code>DynamicPoses</code>. Para dibujar esas poses con Dynamic Xtreme también necesitas <code>DrawingSystem</code>.
|-
| [[#Configurar la cantidad de datos que se transfieren por frame|Configurar la cantidad de datos que se transfieren por frame]]
| <code>GraphicsChange</code> para las cargas gráficas o <code>PalettesChange</code> para las cargas de paletas; ambas si utilizas los dos tipos de carga.
|-
| [[#Crear animaciones de gráficos|Crear animaciones de gráficos]]
| <code>GraphicsChange</code> y <code>PalettesChange</code>, porque el ejemplo carga gráficos y una paleta. Añade <code>PalettesEffects</code> si cambias <code>!PaletteGlobalEffect</code> a 1 para utilizar el efecto global.
|-
| [[#Cambiar paletas durante el juego|Cambiar paletas durante el juego]]
| <code>PalettesChange</code> y, con <code>!PaletteGlobalEffect = 1</code> como en el ejemplo, <code>PalettesEffects</code>. Para cargar sin efecto global, utiliza <code>!PaletteGlobalEffect = 0</code>; en ese caso basta con <code>PalettesChange</code>.
|-
| [[#Cambiar los gráficos del jugador|Cambiar los gráficos del jugador]]
| <code>PlayerFeatures</code>, junto con sus dependencias <code>GraphicsChange</code> y <code>PalettesChange</code>.
|-
| [[#Aplicar un efecto global de paleta|Aplicar un efecto global de paleta]], fijo, cíclico o de transición
| <code>PalettesChange</code> y <code>PalettesEffects</code>.
|}

La animación de gráficos de esta guía copia datos a un destino fijo de VRAM: no necesita <code>DynamicPoses</code> ni <code>DrawingSystem</code>. Para conocer las rutinas y macros que habilita cada funcionalidad, consulta la [[es/Dynamic_Xtreme_ASM_API#Funcionalidades necesarias para utilizar la API|tabla de funcionalidades de la API]].

== Preparar los ejemplos ==

Cada ejemplo es independiente. Guarda el código de nivel en la carpeta correspondiente de UberASMTool y añádelo a su lista. Si reúnes varios ejemplos en un archivo, combina sus bloques <code>load</code>, <code>init</code> y <code>main</code> para no repetir las mismas etiquetas.

* <code>load</code> prepara datos durante la carga del nivel.
* <code>init</code> prepara las opciones al entrar al nivel. El ejemplo de reserva de paletas utiliza este bloque.
* <code>main</code> ejecuta el código durante el juego, una vez por frame.

Los defines y macros de Dynamic Xtreme deben estar disponibles en UberASMTool mediante la integración realizada durante la instalación. Si utilizas gráficos, paletas o efectos adicionales, decláralos en el ASM mediante los includes correspondientes:

<pre>
;#incdyn "DynamicXtreme/MyResources.dynamicinfo"
;#incpale "DynamicXtreme/MyEffect.paleffect"
</pre>

Las rutas son relativas al ASM. Incluye únicamente los archivos que utiliza tu ejemplo. También puedes usar las carpetas tradicionales de Dynamic Xtreme, como se explica en [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos]].

Después de añadir o modificar estos recursos, instala primero Dynamic Xtreme y después UberASMTool. Si solo cambias la lógica del ASM, basta con volver a ejecutar UberASMTool.

Los nombres <code>RAM_LIBRE_...</code> de los ejemplos son marcadores: reemplázalos por direcciones de RAM libre antes de insertar el código. No son defines de Dynamic Xtreme. Reserva la cantidad de bytes indicada y utiliza direcciones distintas para variables que deban coexistir. Comprueba que no las utilicen el juego, Dynamic Xtreme, Lunar Magic u otros recursos; que una dirección esté libre en SMW original no garantiza que siga libre en tu ROM. Puedes buscar direcciones en el [https://www.smwcentral.net/?p=memorymap&game=smw&u=0&address=&sizeOperation=%3D&sizeValue=&region%5B%5D=ram&type=Empty&description= mapa de RAM de SMW Central filtrado por espacios vacíos].

Si utilizas una dirección corta de RAM de SMW que no pertenece a la '''Direct Page''', añade <code>|!addr</code> para aplicar el remapeo correspondiente a LoROM o SA-1. Por ejemplo, al elegir la dirección del temporizador:

<pre>
!AnimationTimer = RAM_LIBRE_ANIM_TIMER|!addr
</pre>

Sustituye <code>RAM_LIBRE_ANIM_TIMER</code> por la dirección elegida y conserva <code>|!addr</code>. Las direcciones de Direct Page se acceden mediante la base D del contexto de ejecución y no utilizan este remapeo. Si eliges una dirección completa de 24 bits, comprueba su banco y que las instrucciones del ejemplo puedan acceder a ella; <code>|!addr</code> está pensado aquí para las direcciones cortas fuera de Direct Page.

== Reservar paletas para otros recursos ==

Si una animación, un HUD u otro recurso necesita una paleta fija, conviene reservarla para que Dynamic Xtreme no la elija al asignar colores a los sprites dinámicos.

Para reservarla, escribe <code>$FFFE</code> en su entrada de <code>DX_Dynamic_Palettes_ID</code>. Cada entrada ocupa 2 bytes. Por ejemplo, la paleta 9 utiliza el desplazamiento <code>$12</code>: 9 × 2.

<pre>
init:
REP #$20
LDA #$FFFE
STA.l DX_Dynamic_Palettes_ID+$12 ; Reservar la paleta 9
SEP #$20
RTL
</pre>

Para reservar varias, escribe el mismo valor en sus entradas:

{| class="wikitable"
! Paleta !! Desplazamiento
|-
| 8 || <code>$10</code>
|-
| 9 || <code>$12</code>
|-
| A || <code>$14</code>
|-
| B || <code>$16</code>
|-
| C || <code>$18</code>
|-
| D || <code>$1A</code>
|-
| E || <code>$1C</code>
|-
| F || <code>$1E</code>
|}

La reserva impide que la asignación automática reclame esa paleta; no carga colores por sí misma. Un recurso configurado para utilizarla manualmente todavía puede cambiar sus colores, por lo que no debes asignársela también a otro recurso que necesite una paleta diferente.

== Elegir el espacio de VRAM para sprites dinámicos ==

Los sprites dinámicos necesitan una parte de VRAM donde cargar sus poses. Elige un espacio que no estés utilizando para gráficos fijos del nivel.

Puedes consultar el [[SMW_VRAM_Map#Levels|mapa de VRAM de SMW en SNESLab]] para ver qué regiones corresponden a SP1, SP2, SP3 y SP4.

Por ejemplo, para permitir que utilicen SP4:

<pre>
init:
LDA #!DynamicSpaceConfigSP4
JSL !DynamicPoseSpaceConfig
RTL
</pre>

Si necesitas más espacio y el nivel lo permite, puedes elegir <code>!DynamicSpaceConfigSP34</code> para SP3 y SP4, o <code>!DynamicSpaceConfigSP234</code> para SP2, SP3 y SP4. Hay más opciones, incluidas medias páginas y configuraciones para compartir espacio con el jugador o DSX.

Los defines disponibles están en <code>DXDefines.asm</code> y en la [[es/Dynamic_Xtreme_ASM_API#Configuraciones_de_espacio_para_poses_dinámicas|tabla de configuraciones de la API]]. Configura el espacio antes de que el nivel empiece a cargar poses; cambiarlo no elimina automáticamente las poses que ya estaban en VRAM.

== Configurar la cantidad de datos que se transfieren por frame ==

<code>DX_Dynamic_MaxDataPerFrame</code> indica cuántos bytes pueden programar las cargas normales de Dynamic Xtreme durante un frame. Lo comparten las poses dinámicas, las animaciones y las demás transferencias realizadas con sus macros.

El valor predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Este ejemplo lo aumenta a <code>$0A00</code>, equivalente a 2560 bytes:

<pre>
init:
REP #$20
LDA #$0A00
STA.l DX_Dynamic_MaxDataPerFrame
SEP #$20
RTL
</pre>

Subirlo permite intentar más cargas durante el mismo frame, pero no aumenta el tiempo que tiene SNES para copiarlas. Si la cantidad total es excesiva, pueden aparecer problemas visuales. Ajusta el valor según el nivel y comprueba el resultado con sus sprites y animaciones funcionando juntos.

Las macros normales devuelven el carry desactivado si una carga no cabe en el límite. En ese caso, conserva lo que ya se muestra y vuelve a intentarlo después. Las variantes <code>Forced</code> se saltan la comprobación y también suman sus bytes al total.

== Crear animaciones de gráficos ==

Este ejemplo crea una animación de gráficos: una tabla indica dónde empieza cada imagen, un temporizador controla cuándo cambiarla y la imagen anterior se mantiene si no se acepta la transferencia.

Declara los archivos del ejemplo en <code>DynamicXtreme/SMMArrow.dynamicinfo</code>:

<pre>
Resources:
SMMArrow.bin
Palettes:
SMMArrowPal.bin
</pre>

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incdyn "DynamicXtreme/SMMArrow.dynamicinfo"

; Aquí pon RAM libre: un byte distinto para cada variable.
!CurrentPoseIndex = RAM_LIBRE_ANIM_POSE
!AnimationTimer = RAM_LIBRE_ANIM_TIMER
!PaletteLoaded = RAM_LIBRE_ANIM_PALETA

; Frames de espera antes de intentar el siguiente cambio.
!TimePerPose = $03

; Bytes de cada imagen: un tile de 8x8 en 4bpp ocupa $0020.
!DataSend = $0200

; Cantidad de imágenes utilizadas.
!NumberOfPoses = $05

; Origen: recurso instalado. También puedes usar !AN2Buffer2.
!Source = !ResourceSMMArrow

; Dirección de destino en VRAM.
!Destination = !BG2Line0

; Paleta instalada y primer color de destino.
!Palette = "SMMArrowPal"
!PaletteDestination = $71

; 0 = sin efecto global; 1 = recibe el efecto global.
!PaletteGlobalEffect = 0

init:
STZ !CurrentPoseIndex
LDA #!TimePerPose
STA !AnimationTimer
STZ !PaletteLoaded

%ForcedTransferToVRAM(#!Destination, #!Source, #((!Source>>16)&$FF), #!DataSend)
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCC .Return
LDA #$01
STA !PaletteLoaded
.Return
RTL

main:
; Reintentar la paleta si no se aceptó durante init.
LDA !PaletteLoaded
BNE .Animate
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCS .PaletteReady
RTL
.PaletteReady
LDA #$01
STA !PaletteLoaded

.Animate
LDA !AnimationTimer
BEQ .NextPose
DEC !AnimationTimer
RTL

.NextPose
LDA !CurrentPoseIndex
INC A
CMP #!NumberOfPoses
BCC .SelectPose
LDA #$00
.SelectPose
STA $05
ASL
TAX

REP #$20
LDA.l PosesTable,x
CLC
ADC.w #!Source
STA $00
SEP #$20

%TransferToVRAM(#!Destination, $00, #((!Source>>16)&$FF), #!DataSend)
BCC .Return

LDA $05
STA !CurrentPoseIndex
LDA #!TimePerPose
STA !AnimationTimer
.Return
RTL

PosesTable:
dw $0000
dw !DataSend*$01
dw !DataSend*$02
dw !DataSend*$03
dw !DataSend*$04
</pre>

'''Qué puedes cambiar'''

* <code>!TimePerPose</code>: tiempo de espera. Con <code>$03</code>, el cambio se intenta cada cuatro frames: tres para descontar el temporizador y uno para realizar el cambio.
* <code>!DataSend</code>: bytes de cada imagen. <code>$0200</code> equivale a 16 tiles de 8×8 en 4bpp.
* <code>!NumberOfPoses</code> y <code>PosesTable</code>: cantidad de imágenes y sus desplazamientos dentro del origen. El ejemplo utiliza las primeras cinco imágenes de <code>SMMArrow.bin</code>. Si añades más, amplía también la tabla.
* <code>!Source</code>: dirección de los gráficos. El ejemplo lee directamente <code>!ResourceSMMArrow</code>; para animar gráficos ya preparados por Lunar Magic puedes usar <code>!AN2Buffer2</code>.
* <code>!Destination</code>: zona de VRAM que se actualizará. Coloca en el nivel tiles que utilicen esa zona y comprueba que otro recurso no la sobrescriba.
* <code>!Palette</code>, <code>!PaletteDestination</code> y <code>!PaletteGlobalEffect</code>: paleta, primer color de destino y participación en el efecto global.

Reemplaza los tres marcadores de RAM del principio por direcciones disponibles durante todo el nivel: cada variable necesita un byte propio. No son scratch temporales. <code>!PaletteLoaded</code> permite reintentar una carga de paleta rechazada sin repetirla después de que haya sido aceptada.

<code>!ResourceSMMArrow</code>, <code>!PaletteSMMArrowPal</code> y <code>!PaletteSMMArrowPalSize</code> se generan al instalar el DynamicInfo y quedan en <code>DXDefines.asm</code>. Sus nombres se normalizan en PascalCase eliminando separadores; en este caso se conservan las mayúsculas de <code>SMMArrow</code> y <code>SMMArrowPal</code>.

Todas las imágenes utilizadas deben quedar en el mismo banco del origen. La carga inicial de gráficos utiliza <code>Forced</code>; los siguientes cambios respetan el límite de datos por frame. Si una carga se rechaza, el código conserva la imagen anterior y vuelve a intentarla en el siguiente frame, sin avanzar el índice ni reiniciar el temporizador.

El temporizador avanza cada vez que se ejecuta <code>main</code>. Si quieres detener la animación durante la pausa o cuando se congela la acción, puedes comprobar <code>$13D4|!addr</code> y <code>$9D</code> antes de descontarlo.

== Cambiar paletas durante el juego ==

Las macros <code>TransferPalette</code> permiten cargar colores y mantener actualizadas las copias que utilizan SMW y Dynamic Xtreme. También se encargan de preparar los efectos de paleta, por lo que no necesitas copiar buffers ni borrar indicadores a mano.

El ejemplo utiliza <code>SMMArrowPal.bin</code>, un archivo de 15 colores (<code>$001E</code> bytes), y cambia los colores 1-F de la paleta 7. El color 0 queda sin modificar.

En <code>DynamicXtreme/SMMArrow.dynamicinfo</code>, declara los gráficos como recurso general y la paleta en <code>Palettes</code>:

<pre>
Resources:
SMMArrow.bin
Palettes:
SMMArrowPal.bin
</pre>

En el ASM del nivel:

<pre>
;#incdyn "DynamicXtreme/SMMArrow.dynamicinfo"

; Aquí pon una RAM libre de un byte.
!PaletteChangePending = RAM_LIBRE_CAMBIO_PALETA

!Palette = "SMMArrowPal"
!PaletteDestination = $71
!PaletteGlobalEffect = 1

init:
LDA #$01
STA !PaletteChangePending
; Continuar con el primer intento de carga.

main:
LDA !PaletteChangePending
BNE .TryTransfer
RTL

.TryTransfer
%TransferPaletteResource(!Palette, #!PaletteDestination, !PaletteGlobalEffect)
BCC .Return

; Confirmar el cambio solo si la llamada fue aceptada.
STZ !PaletteChangePending
.Return
RTL
</pre>

Reemplaza <code>RAM_LIBRE_CAMBIO_PALETA</code> por una dirección de RAM libre de un byte, disponible durante todo el nivel. <code>!PaletteChangePending</code> se pone en 1 al solicitar el cambio y solo vuelve a 0 cuando la macro devuelve el carry activado. Si la llamada falla, el cambio queda pendiente y se reintenta en el siguiente frame. Una vez aceptado, no se repite la carga.

<code>!Palette</code> selecciona el recurso y <code>!PaletteDestination</code> el primer color de destino. <code>!PaletteGlobalEffect</code>, utilizado como último parámetro de la macro, elige cómo se carga:

* <code>1</code>: prepara los colores originales para que reciban el efecto global antes de mostrarse. También deja la paleta preparada si todavía no has seleccionado un efecto.
* <code>0</code>: carga los colores sin efecto global y excluye esa paleta del efecto. Además actualiza los buffers de SMW, necesarios para evitar problemas de colores durante la animación de victoria del goal.

Para cargar la misma paleta sin efecto global, cambia únicamente este define; conserva la comprobación del carry:

<pre>
!PaletteGlobalEffect = 0
</pre>

Si los efectos están deshabilitados en la instalación, ambas opciones realizan una carga directa. Cuando están habilitados y utilizas <code>1</code>, el sistema carga el resultado ya procesado; no se muestra primero la paleta sin efecto durante un frame.

<code>SMMArrowPal</code> utiliza los defines <code>!PaletteSMMArrowPal</code> y <code>!PaletteSMMArrowPalSize</code>, generados desde <code>Palettes</code> del DynamicInfo y publicados en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores y poniendo en mayúscula la inicial de cada palabra. En este caso se conserva <code>SMMArrowPal</code> tal como está escrito.

Para solicitar de nuevo el cambio durante el juego, pon <code>!PaletteChangePending</code> en 1 cuando se cumpla la condición que elijas. No lo hagas cada frame si la paleta no cambia. En una carga directa, el carry activado indica que se programó la transferencia; con efecto global, indica que los colores originales quedaron preparados, no que el resultado ya esté en pantalla.

La opción de efecto se aplica a toda la paleta de 16 colores. Si cargas colores para recibir un efecto global, prepara todos sus colores visibles, como los 15 de este ejemplo; no cambies solo unos pocos esperando conservar una base que todavía no has preparado.

Si eliges una paleta de sprites 8-F para un uso fijo, resérvala primero como se explica al comienzo del artículo. Estas macros no realizan asignación automática. Para cargar desde una dirección, un puntero o una tabla, consulta [[es/Dynamic_Xtreme_ASM_API#Cargar_colores_con_TransferPalette|Cargar colores con TransferPalette en la API]].

== Cambiar los gráficos del jugador ==

Este ejemplo alterna entre el jugador original y Geno al pulsar arriba. Sus defines permiten elegir los gráficos y las cuatro paletas: Mario, Luigi, Mario con fuego y Luigi con fuego. También vuelve a seleccionar la paleta cuando cambia el estado del jugador.

Necesita <code>PlayerFeatures</code> habilitado. Los gráficos personalizados deben utilizar la misma organización de poses que los originales; cambiar el origen no adapta un spritesheet de otro formato.

En <code>DynamicXtreme/Geno.dynamicinfo</code>, declara:

<pre>
Resources:
Geno.bin
Palettes:
GenoPal.bin
GenoPalPlayer2.bin
FireGenoPal.bin
FireGenoPalPlayer2.bin
</pre>

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incdyn "DynamicXtreme/Geno.dynamicinfo"

; Aquí pon una RAM libre de dos bytes consecutivos.
!Last0D82 = RAM_LIBRE_JUGADOR_2_BYTES

; Gráficos del jugador personalizado.
!PlayerGFXResource = !ResourceGeno

; Paletas: jugador 1, jugador 2 y sus variantes con fuego.
!PlayerGFXPalette = !PaletteGenoPal
!PlayerGFXPalettePlayer2 = !PaletteGenoPalPlayer2
!PlayerGFXFirePalette = !PaletteFireGenoPal
!PlayerGFXFirePalettePlayer2 = !PaletteFireGenoPalPlayer2

; Botón de cambio: $08 = arriba.
!ChangeButton = $08

init:
REP #$20
LDA $0D82|!addr
STA !Last0D82
SEP #$20

main:
LDA !ButtonDown_BYETUDLR
AND #!ChangeButton
BNE .Change

REP #$20
LDA $0D82|!addr
CMP !Last0D82
BNE .Reload
SEP #$20
RTL

.Change
LDA.l DX_Dynamic_Player_GFX_BNK
CMP.b #!GFX32Buffer>>16
BEQ .ChooseGeno
JMP .Mario
.ChooseGeno
JMP .Geno

.Reload
SEP #$20
LDA.l DX_Dynamic_Player_GFX_BNK
CMP.b #!GFX32Buffer>>16
BNE .Geno
JMP .Mario

.Geno
; Obtener 0, 1, 2 o 3 según jugador y estado de fuego.
REP #$20
LDA $0D82|!addr
SEC
SBC #!PlayerBasePalette
STA $00
SEP #$20
%DivW($01, $00, #$14)

; Cada dirección de GenoPals ocupa tres bytes.
LDA !DivisionResult
ASL
CLC
ADC !DivisionResult
TAX

; Conservar el origen elegido y preparar los colores 2-5.
REP #$20
LDA.l GenoPals,x
STA $03
CLC
ADC #$0002
STA $00
SEP #$20
LDA.l GenoPals+2,x
STA $02
STA $05

%TransferPaletteFromPointer($00, #$82, $0008, 0)
BCS .ApplyGeno
RTL

.ApplyGeno
REP #$20
LDA.w #!PlayerGFXResource
STA.l DX_Dynamic_Player_GFX_Addr
LDA.w #(!PlayerGFXResource>>16)&$00FF
STA.l DX_Dynamic_Player_GFX_BNK

; La rutina del jugador carga los colores 6-F.
LDA $03
CLC
ADC #$000A
STA.l DX_Dynamic_Player_Palette_Addr
SEP #$20
LDA $05
STA.l DX_Dynamic_Player_Palette_BNK
JMP .ConfirmSelection

.Mario
%TransferPaletteFromAddress(!PlayerPaletteColor2To5, #$82, $0008, 0)
BCS .ApplyMario
RTL

.ApplyMario
REP #$20
LDA.w #!GFX32Buffer
STA.l DX_Dynamic_Player_GFX_Addr
LDA $0D82|!addr
STA.l DX_Dynamic_Player_Palette_Addr
LDA.w #(!GFX32Buffer>>16)&$00FF
STA.l DX_Dynamic_Player_GFX_BNK
LDA #$0000
STA.l DX_Dynamic_Player_Palette_BNK
SEP #$20

.ConfirmSelection
REP #$20
LDA $0D82|!addr
STA !Last0D82
SEP #$20
RTL

GenoPals:
dl !PlayerGFXPalette
dl !PlayerGFXPalettePlayer2
dl !PlayerGFXFirePalette
dl !PlayerGFXFirePalettePlayer2
</pre>

'''Qué puedes cambiar'''

* <code>!PlayerGFXResource</code>: gráficos del personaje personalizado.
* Los cuatro defines <code>!PlayerGFX...Palette...</code>: direcciones de sus paletas, en el orden de la tabla <code>GenoPals</code>.
* <code>!ChangeButton</code>: botón que alterna entre los personajes. Utiliza los bits del control <code>BYETUDLR</code>; <code>$08</code> corresponde a arriba.
* <code>!Last0D82</code>: reemplaza <code>RAM_LIBRE_JUGADOR_2_BYTES</code> por una dirección de RAM libre con dos bytes consecutivos disponibles. Guarda la selección de paleta del juego; ninguno de esos bytes debe estar ocupado por otro código.

<code>!ResourceGeno</code> y los defines <code>!PaletteGenoPal</code>, <code>!PaletteGenoPalPlayer2</code>, <code>!PaletteFireGenoPal</code> y <code>!PaletteFireGenoPalPlayer2</code> se generan desde el DynamicInfo y quedan en <code>DXDefines.asm</code>. Los nombres usan PascalCase eliminando espacios, guiones y guiones bajos, y conservando las mayúsculas ya presentes.

Cada archivo de paleta contiene los colores 1-F. Se omite su primer color para copiar los colores 2-5; los últimos diez comienzan en <code>+$0A</code> y los utiliza la rutina del jugador.

Las cargas de los colores 2-5 utilizan <code>TransferPalette</code>, que también actualiza los buffers de SMW. El ejemplo no confirma el cambio de gráficos si esa transferencia es rechazada. Un cambio pendiente por el estado del jugador se vuelve a intentar mientras no coincida con <code>!Last0D82</code>; si se rechaza un cambio solicitado con el botón, vuelve a pulsarlo.

El código distingue al jugador original por el banco de <code>!GFX32Buffer</code>. Si lo adaptas para alternar entre varios personajes personalizados en ROM, necesitarás otra forma de recordar cuál está seleccionado.

Este ejemplo carga la paleta del jugador sin efecto global. No basta con cambiar a <code>1</code> el parámetro de una carga de cuatro colores para añadirle un efecto: en ese caso hay que preparar todos los colores visibles de la paleta 8 y respetar su carga especial.

== Aplicar un efecto global de paleta ==

Los siguientes ejemplos permiten aplicar un efecto fijo, recorrer efectos en un ciclo o realizar una transición que se detiene al terminar. Puedes elegir cada paleta por separado e incluir el color fijo. Los códigos de ciclo y transición también permiten configurar la velocidad con <code>!Delay</code>.

En los archivos <code>*.paleffect</code>, <code>EffectType</code> selecciona el tipo de efecto. Los ratios utilizan valores de 0 a 127 y los valores <code>Channel</code>, de 0 a 31.

=== Elegir las paletas afectadas ===

En cada código, cambia <code>!P0</code> a <code>!PF</code> a 1 para incluir la paleta correspondiente o a 0 para excluirla. <code>!EnableFixedColor</code> controla el color fijo y <code>!EnableColor00</code> permite incluir también el color 0,0.

Las máscaras <code>!EnableBG</code>, <code>!EnableSP</code> y <code>!EnableColors</code> se calculan a partir de esos ajustes. No necesitas modificarlas a mano. En la API actual, el bit bajo corresponde a la primera paleta de cada grupo:

{| class="wikitable"
! Valor del bit !! Paleta de fondo !! Paleta de sprites
|-
| <code>$01</code> || 0 || 8
|-
| <code>$02</code> || 1 || 9
|-
| <code>$04</code> || 2 || A
|-
| <code>$08</code> || 3 || B
|-
| <code>$10</code> || 4 || C
|-
| <code>$20</code> || 5 || D
|-
| <code>$40</code> || 6 || E
|-
| <code>$80</code> || 7 || F
|}

El color fijo y el color 0,0 utilizan <code>DX_PPU_ColorEffect_Enable</code>: bit <code>$01</code> y bit <code>$02</code>, respectivamente.

En sprites con asignación dinámica, configura también el bit E de <code>PaletteOption</code>. Si cargas paletas mediante <code>TransferPalette</code>, su último parámetro determina si esas paletas participan en el efecto global. Evita que otro código vuelva a escribir máscaras distintas sin tener en cuenta esa configuración.

=== Aplicar un efecto fijo ===

Este ejemplo aplica el efecto que indiques en <code>!PaletteEffetID</code>. La configuración mostrada habilita todas las paletas y el color fijo, y selecciona el último efecto de <code>DecreaseSaturation</code>.

Guarda el siguiente contenido en <code>DynamicXtreme/DecreaseSaturation.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel2": 0, "Ratio2": 4, "EffectType": 11},
{"Channel2": 0, "Ratio2": 8, "EffectType": 11},
{"Channel2": 0, "Ratio2": 12, "EffectType": 11},
{"Channel2": 0, "Ratio2": 16, "EffectType": 11},
{"Channel2": 0, "Ratio2": 20, "EffectType": 11},
{"Channel2": 0, "Ratio2": 25, "EffectType": 11},
{"Channel2": 0, "Ratio2": 29, "EffectType": 11},
{"Channel2": 0, "Ratio2": 33, "EffectType": 11},
{"Channel2": 0, "Ratio2": 37, "EffectType": 11},
{"Channel2": 0, "Ratio2": 41, "EffectType": 11},
{"Channel2": 0, "Ratio2": 45, "EffectType": 11},
{"Channel2": 0, "Ratio2": 49, "EffectType": 11},
{"Channel2": 0, "Ratio2": 53, "EffectType": 11},
{"Channel2": 0, "Ratio2": 57, "EffectType": 11},
{"Channel2": 0, "Ratio2": 61, "EffectType": 11},
{"Channel2": 0, "Ratio2": 66, "EffectType": 11},
{"Channel2": 0, "Ratio2": 70, "EffectType": 11},
{"Channel2": 0, "Ratio2": 74, "EffectType": 11},
{"Channel2": 0, "Ratio2": 78, "EffectType": 11},
{"Channel2": 0, "Ratio2": 82, "EffectType": 11},
{"Channel2": 0, "Ratio2": 86, "EffectType": 11},
{"Channel2": 0, "Ratio2": 90, "EffectType": 11},
{"Channel2": 0, "Ratio2": 94, "EffectType": 11},
{"Channel2": 0, "Ratio2": 98, "EffectType": 11},
{"Channel2": 0, "Ratio2": 102, "EffectType": 11},
{"Channel2": 0, "Ratio2": 107, "EffectType": 11},
{"Channel2": 0, "Ratio2": 111, "EffectType": 11},
{"Channel2": 0, "Ratio2": 115, "EffectType": 11},
{"Channel2": 0, "Ratio2": 119, "EffectType": 11},
{"Channel2": 0, "Ratio2": 123, "EffectType": 11},
{"Channel2": 0, "Ratio2": 127, "EffectType": 11},
{"Channel2": 0, "Ratio2": 127, "EffectType": 11}
]
}
</pre>

El archivo define 32 efectos. <code>EffectType = 11</code> corresponde a <code>MixS</code>; <code>Channel2 = 0</code> indica que se reduce la saturación y <code>Ratio2</code> controla cuánto. El último efecto utiliza 127, que aplica el cambio completo.

El código ASM es:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/DecreaseSaturation.paleffect"

; 1 = incluir la paleta en el efecto; 0 = excluirla.
!P0 = 1
!P1 = 1
!P2 = 1
!P3 = 1
!P4 = 1
!P5 = 1
!P6 = 1
!P7 = 1

!P8 = 1
!P9 = 1
!PA = 1
!PB = 1
!PC = 1
!PD = 1
!PE = 1
!PF = 1

!EnableFixedColor = 1
!EnableColor00 = 0

; Efecto que se aplica al entrar al nivel.
!PaletteEffetID = !PaletteEffectIDDecreaseSaturation31

; Máscaras calculadas: no hace falta modificarlas.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!PaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL
</pre>

'''Qué puedes cambiar'''

* <code>!P0</code> a <code>!PF</code>: paletas afectadas.
* <code>!EnableFixedColor</code> y <code>!EnableColor00</code>: participación de esos colores.
* <code>!PaletteEffetID</code>: efecto seleccionado. Puedes utilizar cualquier ID generado desde tu archivo de efectos, no solo el último de este ejemplo.

Los defines <code>!PaletteEffectIDDecreaseSaturation0</code> a <code>!PaletteEffectIDDecreaseSaturation31</code> se generan desde el <code>*.paleffect</code> y quedan en <code>DXDefines.asm</code>. El nombre usa PascalCase eliminando espacios, guiones y guiones bajos, y conservando las mayúsculas ya presentes.

La selección se realiza en <code>init</code>; no hace falta repetirla cada frame. Para quitar el efecto, escribe 0 en el ID global y deja las paletas habilitadas para que el sistema restaure sus colores originales:

<pre>
REP #$20
LDA #$0000
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
</pre>

=== Hacer que el efecto se repita en un ciclo ===

Este ejemplo recorre una secuencia de efectos y vuelve al primero. Puedes configurar la velocidad, el primer y último ID y las paletas afectadas. La configuración mostrada incluye solo la paleta 0 y el color fijo.

Guarda el siguiente contenido en <code>DynamicXtreme/Hue.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel1": 1, "Ratio1": 127, "EffectType": 9},
{"Channel1": 2, "Ratio1": 127, "EffectType": 9},
{"Channel1": 3, "Ratio1": 127, "EffectType": 9},
{"Channel1": 4, "Ratio1": 127, "EffectType": 9},
{"Channel1": 5, "Ratio1": 127, "EffectType": 9},
{"Channel1": 6, "Ratio1": 127, "EffectType": 9},
{"Channel1": 7, "Ratio1": 127, "EffectType": 9},
{"Channel1": 8, "Ratio1": 127, "EffectType": 9},
{"Channel1": 9, "Ratio1": 127, "EffectType": 9},
{"Channel1": 10, "Ratio1": 127, "EffectType": 9},
{"Channel1": 11, "Ratio1": 127, "EffectType": 9},
{"Channel1": 12, "Ratio1": 127, "EffectType": 9},
{"Channel1": 13, "Ratio1": 127, "EffectType": 9},
{"Channel1": 14, "Ratio1": 127, "EffectType": 9},
{"Channel1": 15, "Ratio1": 127, "EffectType": 9},
{"Channel1": 16, "Ratio1": 127, "EffectType": 9},
{"Channel1": 17, "Ratio1": 127, "EffectType": 9},
{"Channel1": 18, "Ratio1": 127, "EffectType": 9},
{"Channel1": 19, "Ratio1": 127, "EffectType": 9},
{"Channel1": 20, "Ratio1": 127, "EffectType": 9},
{"Channel1": 21, "Ratio1": 127, "EffectType": 9},
{"Channel1": 22, "Ratio1": 127, "EffectType": 9},
{"Channel1": 23, "Ratio1": 127, "EffectType": 9},
{"Channel1": 24, "Ratio1": 127, "EffectType": 9},
{"Channel1": 25, "Ratio1": 127, "EffectType": 9},
{"Channel1": 26, "Ratio1": 127, "EffectType": 9},
{"Channel1": 27, "Ratio1": 127, "EffectType": 9},
{"Channel1": 28, "Ratio1": 127, "EffectType": 9},
{"Channel1": 29, "Ratio1": 127, "EffectType": 9},
{"Channel1": 30, "Ratio1": 127, "EffectType": 9},
{"Channel1": 31, "Ratio1": 127, "EffectType": 9},
{"Channel1": 31, "Ratio1": 127, "EffectType": 9}
]
}
</pre>

El archivo define 32 efectos de tono. <code>EffectType = 9</code> corresponde a <code>MixH</code> y <code>Ratio1 = 127</code> aplica por completo el tono seleccionado.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/Hue.paleffect"

; 1 = incluir la paleta en el efecto; 0 = excluirla.
!P0 = 1
!P1 = 0
!P2 = 0
!P3 = 0
!P4 = 0
!P5 = 0
!P6 = 0
!P7 = 0

!P8 = 0
!P9 = 0
!PA = 0
!PB = 0
!PC = 0
!PD = 0
!PE = 0
!PF = 0

!EnableFixedColor = 1
!EnableColor00 = 0

; Valores permitidos: $00, $01, $03, $07, $0F, $1F, $3F, $7F y $FF.
!Delay = $03

!StartingPaletteEffetID = !PaletteEffectIDHue0
!EndPaletteEffetID = !PaletteEffectIDHue31

; Máscaras calculadas: no hace falta modificarlas.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!StartingPaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL

main:
LDA $14
AND #!Delay
BNE .Return

REP #$20
LDA.l DX_Dynamic_Palettes_GlobalEffectID
CMP #!EndPaletteEffetID
BCS .Restart
INC A
BRA .Store
.Restart
LDA #!StartingPaletteEffetID
.Store
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
.Return
RTL
</pre>

'''Qué puedes cambiar'''

* <code>!P0</code> a <code>!PF</code>, <code>!EnableFixedColor</code> y <code>!EnableColor00</code>: colores afectados.
* <code>!Delay</code>: separación entre cambios. <code>$00</code> cambia cada frame, <code>$01</code> cada dos, <code>$03</code> cada cuatro y <code>$07</code> cada ocho. Utiliza únicamente los valores indicados en el comentario.
* <code>!StartingPaletteEffetID</code> y <code>!EndPaletteEffetID</code>: primer y último efecto del ciclo. Deben pertenecer a una secuencia de IDs consecutivos, con el inicio menor o igual que el final.

El ciclo muestra el último ID antes de volver al primero. Utiliza <code>$14</code> para marcar el momento de los cambios; por ello, el primer intervalo depende del valor que tenga ese contador al entrar al nivel. Si quieres detenerlo al congelarse la acción, comprueba también <code>$9D</code> y <code>$13D4|!addr</code> al comienzo de <code>main</code>.

Los defines <code>!PaletteEffectIDHue0</code> a <code>!PaletteEffectIDHue31</code> se generan desde el <code>*.paleffect</code> y quedan en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores; en este caso conserva <code>Hue</code>.

=== Hacer una transición que se detiene al terminar ===

Este ejemplo avanza desde el efecto inicial hasta el final y mantiene ese último resultado. Puedes configurar las paletas afectadas, el color fijo, la velocidad y el rango de IDs.

Guarda el siguiente contenido en <code>DynamicXtreme/Night.paleffect</code>:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
{
"Effects": [
{"Channel1": 0, "Channel2": 0, "Ratio1": 0, "Ratio2": 0, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 4, "Ratio2": 4, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 8, "Ratio2": 8, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 12, "Ratio2": 12, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 16, "Ratio2": 16, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 20, "Ratio2": 20, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 25, "Ratio2": 25, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 29, "Ratio2": 29, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 33, "Ratio2": 33, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 37, "Ratio2": 37, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 41, "Ratio2": 41, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 45, "Ratio2": 45, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 49, "Ratio2": 49, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 53, "Ratio2": 53, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 57, "Ratio2": 57, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 61, "Ratio2": 61, "EffectType": 2},
{"Channel1": 0, "Channel2": 0, "Ratio1": 66, "Ratio2": 66, "EffectType": 2}
]
}
</pre>

La transición tiene 17 pasos. <code>EffectType = 2</code> corresponde a <code>MixRG</code>: reduce el rojo y el verde sin modificar el azul. Los ratios aumentan de 0 a 66 para oscurecer los colores gradualmente sin eliminar por completo el rojo y el verde.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
;#incpale "DynamicXtreme/Night.paleffect"

; 1 = incluir la paleta en el efecto; 0 = excluirla.
!P0 = 1
!P1 = 1
!P2 = 1
!P3 = 1
!P4 = 1
!P5 = 1
!P6 = 1
!P7 = 1

!P8 = 1
!P9 = 1
!PA = 1
!PB = 1
!PC = 1
!PD = 1
!PE = 1
!PF = 1

!EnableFixedColor = 1
!EnableColor00 = 0

; Valores permitidos: $00, $01, $03, $07, $0F, $1F, $3F, $7F y $FF.
!Delay = $03

!StartingPaletteEffetID = !PaletteEffectIDNight0
!EndPaletteEffetID = !PaletteEffectIDNight16

; Máscaras calculadas: no hace falta modificarlas.
!EnableBG = !P0|(!P1<<1)|(!P2<<2)|(!P3<<3)|(!P4<<4)|(!P5<<5)|(!P6<<6)|(!P7<<7)
!EnableSP = !P8|(!P9<<1)|(!PA<<2)|(!PB<<3)|(!PC<<4)|(!PD<<5)|(!PE<<6)|(!PF<<7)
!EnableColors = !EnableFixedColor|(!EnableColor00<<1)

init:
LDA #!EnableBG
STA.l DX_Dynamic_Palettes_GlobalBGEnable
LDA #!EnableSP
STA.l DX_Dynamic_Palettes_GlobalSPEnable
LDA #!EnableColors
STA.l DX_PPU_ColorEffect_Enable

REP #$20
LDA #!StartingPaletteEffetID
STA.l DX_Dynamic_Palettes_GlobalEffectID
SEP #$20
RTL

main:
LDA $14
AND #!Delay
BNE .Return

REP #$20
LDA.l DX_Dynamic_Palettes_GlobalEffectID
CMP #!EndPaletteEffetID
BCS .Finished
INC A
STA.l DX_Dynamic_Palettes_GlobalEffectID
.Finished
SEP #$20
.Return
RTL
</pre>

'''Qué puedes cambiar'''

* <code>!P0</code> a <code>!PF</code>, <code>!EnableFixedColor</code> y <code>!EnableColor00</code>: colores afectados.
* <code>!Delay</code>: tiempo entre cambios, con los mismos valores permitidos en el ejemplo de ciclo.
* <code>!StartingPaletteEffetID</code> y <code>!EndPaletteEffetID</code>: primer y último efecto. Deben ser IDs consecutivos en orden ascendente.

Los defines <code>!PaletteEffectIDNight0</code> a <code>!PaletteEffectIDNight16</code> se generan desde <code>Night.paleffect</code> y quedan en <code>DXDefines.asm</code>. Los nombres usan PascalCase eliminando separadores; aquí se conserva <code>Night</code>.

Este ejemplo cambia entre efectos de mezcla. Para una transición hacia otra paleta completa, utiliza <code>PalTransitionRGB</code> o <code>PalTransitionHSL</code>, explicados en [[es/Dynamic_Xtreme_files_and_formats#Transiciones_de_paleta|Archivos y formatos]].

es/Dynamic Xtreme ASM API

2026-10-25T17:36:52Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_ASM_API}}

En este artículo se explica cómo usar las rutinas y macros de Dynamic Xtreme desde código ASM. Cada entrada indica para qué sirve la llamada, qué datos debes preparar y qué obtienes al ejecutarla, junto con un ejemplo.

Para aprender a organizar un sprite completo, consulta la [[es/Dynamic_Xtreme_sprite_creation_guide|guía de creación de sprites]].

== Funcionalidades necesarias para utilizar la API ==

Las rutinas, macros y variables disponibles dependen de las funcionalidades seleccionadas al instalar Dynamic Xtreme. Esta tabla indica qué debes habilitar para utilizar cada sistema:

{| class="wikitable"
! Funcionalidad !! Rutinas y macros que permite utilizar !! Dependencias y detalles
|-
| <code>GraphicsChange</code>
| [[#PPU|Transferencias a VRAM]]: <code>TransferToVRAM</code> y sus variantes <code>FromAddr</code>, <code>Resource</code>, <code>WithLenght</code> y <code>Forced</code>.
| Proporciona las cargas de gráficos. También es necesaria para <code>DynamicPoses</code> y <code>PlayerFeatures</code>.
|-
| <code>DynamicPoses</code>
| [[#DefineDynamicSpaceConfig|DefineDynamicSpaceConfig]], [[#DynamicPoseSpaceConfig|DynamicPoseSpaceConfig]], [[#TakeDynamicRequest|TakeDynamicRequest]], [[#DynamicRoutine|DynamicRoutine]], <code>SetPropertyAndOffset</code>, [[#Upload|!Upload]], <code>!UploadWithoutPoseOffset</code> y las macros generales <code>GeneralUpload</code>, <code>Upload</code> y <code>StandardSpriteUpload</code>.
| Requiere <code>GraphicsChange</code>. Para dibujar las poses obtenidas también necesitas <code>DrawingSystem</code>.
|-
| <code>DrawingSystem</code>
| [[#DXDraw|!DXDraw]], <code>!DXDrawWithOffset</code> y las macros generales <code>Draw</code>, <code>StandardSpriteDraw</code> y [[#DrawStatic|DrawStatic]]. Incluye las rutinas de dibujo y comprobación de tiles que utiliza el sistema.
| El dibujo de poses dinámicas también requiere <code>DynamicPoses</code>. <code>DrawStatic</code> puede dibujar poses estáticas sin habilitar el sistema de poses dinámicas.
|-
| <code>PalettesChange</code>
| <code>AssignPalette</code>, [[#PaletteAssignment|!PaletteAssignment]], <code>!PaletteAssignmentNoUpload</code>, <code>!ReplacePalette</code> y sus macros generales; <code>LoadPaletteIDAndAddress</code>; las macros [[#Cargar colores con TransferPalette|TransferPalette]] y las [[#PPU|transferencias a CGRAM]].
| Proporciona la asignación y carga de paletas. Para aplicar efectos también debes habilitar <code>PalettesEffects</code>.
|-
| <code>PalettesEffects</code>
| [[#Efectos de paleta|SetRGBBase, SetHSLBase, Mix, MixAndMerge, PaletteTransition, DoEffect y conversiones RGB/HSL]], con sus variantes. También permite utilizar <code>ConcatenateRGBPaletteEffectToGlobal</code> y <code>ConcatenateHSLPaletteEffectToGlobal</code>, como aliases de sprites o macros generales.
| Requiere <code>PalettesChange</code>. Permite aplicar el efecto global mediante la asignación de paletas o <code>TransferPalette</code>.
|-
| <code>PlayerFeatures</code>
| Permite personalizar los gráficos y las paletas del jugador mediante las [[#Jugador y Yoshi|variables del jugador]]. No añade una familia de llamadas propia a las categorías anteriores.
| Requiere <code>GraphicsChange</code> y <code>PalettesChange</code>.
|-
| <code>YoshiFeatures</code>
| Permite personalizar los gráficos de Yoshi mediante las [[#Jugador y Yoshi|variables de Yoshi]].
| Requiere <code>PlayerFeatures</code>, junto con sus dependencias.
|-
| <code>Free7E2000</code>
| No añade llamadas a esta API.
| Libera y reorganiza el uso del espacio de RAM correspondiente. No es un requisito adicional para las macros de carga o dibujo. Se deshabilita en SA-1.
|-
| <code>ControllerOptimization</code>, <code>FixedColorOptimization</code>, <code>KevinLMVRAMOptimization</code> y <code>StatusBarOptimization</code>
| No añaden familias de llamadas a esta API.
| Modifican el funcionamiento interno de sus respectivos sistemas. No necesitas habilitarlas para obtener las macros de poses, dibujo, paletas o matemáticas.
|-
| Sin una funcionalidad adicional
| [[#Matemáticas|Mul, Div y sus variantes W y After...]].
| Las macros de matemáticas se incluyen desde <code>DXDefines.asm</code> independientemente de las opciones anteriores.
|}

Las macros de PPU se incluyen si está habilitado <code>GraphicsChange</code> o <code>PalettesChange</code>, pero utiliza las de VRAM con <code>GraphicsChange</code> y las de CGRAM con <code>PalettesChange</code>. Que Asar reconozca el nombre de una macro no significa que estén habilitadas las listas y variables que esa macro necesita.

Para cargar '''y dibujar''' poses dinámicas, habilita <code>GraphicsChange</code>, <code>DynamicPoses</code> y <code>DrawingSystem</code>. Si el sprite también carga paletas, añade <code>PalettesChange</code>; si utiliza efectos, añade <code>PalettesEffects</code>.

'''Integración con las herramientas'''

{| class="wikitable"
! Contexto !! Archivos y llamadas
|-
| PIXI
| La instalación copia los defines generales a <code>asm/ExtraDefines</code> y las rutinas compartidas a <code>routines</code>. Para los aliases de sprites, incluye <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code> o <code>ExtendedSpriteDefines.asm</code>, según corresponda. Las diferencias entre tipos se indican en cada llamada.
|-
| UberASMTool
| La instalación enlaza <code>ExtraDefines/DXDefines.asm</code> desde <code>other/macro_library.asm</code>. Utiliza las macros generales y las rutinas del parche con sus parámetros; los aliases como <code>!Upload</code> pertenecen a los archivos de defines para sprites de PIXI.
|-
| GPS
| La instalación enlaza <code>ExtraDefines/DXDefines.asm</code> desde <code>defines.asm</code>. Utiliza las macros generales y las rutinas del parche, preparando sus entradas desde el código del bloque.
|}

Estas integraciones se preparan para las herramientas configuradas durante la instalación. Si Asar no encuentra un nombre, comprueba la funcionalidad necesaria, los archivos incluidos y, si es un define generado, su escritura exacta en <code>DXDefines.asm</code>. Después de cambiar las funcionalidades o los recursos, reinstala Dynamic Xtreme y vuelve a ejecutar las herramientas que utilizan sus defines, como explica la [[es/Dynamic_Xtreme_Quick_Start|guía de inicio rápido]].

== Variables y defines ==

<code>DXDefines.asm</code> reúne los nombres que utiliza Dynamic Xtreme para acceder a sus variables, configuraciones, recursos y rutinas. Algunos representan datos que cambian durante el juego; otros son valores fijos o se generan al instalar los recursos.

Los nombres de variables generales comienzan con <code>DX_</code> y se escriben sin <code>!</code>, por ejemplo <code>DX_Timer</code>. Los defines como <code>!DynamicPoseIDMySprite000</code> sí llevan <code>!</code>. Conserva la escritura exacta del nombre que aparece en el archivo.

Las variables disponibles dependen de las funciones habilitadas durante la instalación. No es necesario memorizar todas: busca la categoría del sistema con el que estás trabajando.

=== Variables generales ===

En las tablas, el tamaño indica cuántos bytes ocupa un valor. Para una tabla se indica también cuántos valores contiene. Las variables marcadas como internas las actualiza Dynamic Xtreme; normalmente se utilizan las rutinas de la API para trabajar con ellas.

==== Contadores y cantidad de datos por frame ====

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Timer</code> || 2 bytes || Cuenta los frames en los que se ejecuta Dynamic Xtreme. Continúa durante la pausa y cuando se congela la acción. El sistema lo utiliza para saber cuándo se usó una pose por última vez.
|-
| <code>DX_SyncTimer</code> || 2 bytes || Cuenta los frames, pero se detiene cuando el juego está pausado o la acción está congelada. Puede utilizarse para animaciones que deban detenerse con el juego.
|-
| <code>DX_Dynamic_CurrentDataSend</code> || 2 bytes || Cantidad de bytes que ya se programaron para transferir durante el frame actual. La actualizan las rutinas de carga.
|-
| <code>DX_Dynamic_MaxDataPerFrame</code> || 2 bytes || Límite de bytes que las cargas normales pueden programar en un frame. Las variantes <code>Forced</code> pueden superarlo.
|}

==== Poses cargadas en VRAM ====

Estas tablas permiten al sistema saber qué poses están cargadas, dónde están y cuáles siguen en uso. Son datos internos de la caché; para solicitar una pose utiliza <code>!Upload</code> o <code>!TakeDynamicRequest</code>.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 byte || Cantidad de poses registradas actualmente en la caché.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 valores de 1 byte || Ayuda a encontrar las poses por su ID.
|-
| <code>DX_Dynamic_Pose_ID</code> || 128 valores de 2 bytes || ID de cada pose registrada.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 valores de 1 byte || Posición de los gráficos de cada pose en el espacio dinámico de VRAM, medida en bloques de 16×16.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 128 valores de 2 bytes || Valor de <code>DX_Timer</code> de la última vez que se utilizó cada pose. Evita reemplazar gráficos que todavía se están mostrando.
|-
| <code>DX_Dynamic_Tile_Size</code> / <code>DX_Dynamic_Tile_Pose</code> || 128 bytes compartidos || Describen las partes libres u ocupadas de VRAM. Son dos nombres para el mismo espacio de memoria.
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 valores de 1 byte || Ayuda al sistema a recorrer las partes libres y ocupadas de VRAM.
|}

==== Paletas y efecto global ====

Las tablas de 16 paletas utilizan el orden 0-F. En las tablas de valores de 2 bytes, la paleta 1 comienza en <code>+2</code>, la 2 en <code>+4</code>, y así sucesivamente.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 byte || Cada bit indica si una de las paletas 0-7 recibe el efecto global.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 byte || Cada bit indica si una de las paletas de sprites 8-F recibe el efecto global.
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 bytes || ID del efecto global que se quiere aplicar. El valor 0 indica que no se aplica un efecto global.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectID</code> || 2 bytes || Último efecto global revisado por el sistema. Se utiliza para detectar cambios.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 16 valores de 2 bytes || Último efecto global calculado para cada paleta. <code>$FFFF</code> significa que aún no hay un resultado; <code>$FFFE</code>, que hay una actualización pendiente y se conserva el resultado anterior.
|-
| <code>DX_Dynamic_Palettes_ID</code> || 16 valores de 2 bytes || ID asociado a cada paleta. <code>$FFFF</code> indica que está libre; <code>$FFFE</code> la excluye de la selección automática.
|-
| <code>DX_Dynamic_Palettes_Updated</code> || 16 valores de 1 byte || Indica cuáles paletas ya se actualizaron durante el frame. Uso interno.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 valores de 1 byte || Mientras sea distinto de 0, protege la paleta para que no sea reemplazada por otra asignación automática. Las llamadas que la utilizan vuelven a ponerlo en 2.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 byte || Registra qué paletas de sprites se utilizan con efectos. Uso interno del manejo de paletas.
|}

Para reservar una paleta de sprites y evitar que la selección automática la utilice, su entrada de <code>DX_Dynamic_Palettes_ID</code> debe contener <code>$FFFE</code>. Haz la reserva antes de que los sprites comiencen a solicitar paletas.

==== Copias de colores y resultados de efectos ====

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 bytes || Copia de trabajo de las 256 entradas de color, con 2 bytes por color. Es la fuente de las variantes <code>SetRGBBaseDefault</code> y <code>SetHSLBaseDefault</code>.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 bytes || Colores originales separados en rojo, verde y azul: 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 bytes || Colores originales separados en tono, saturación y luminosidad: 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_LocalEffectBuffer</code> || 768 bytes || Espacio de trabajo para el resultado de un efecto local antes de combinarlo con el global.
|-
| <code>DX_PPU_CGRAM_LocalEffectID</code> || 16 valores de 2 bytes || ID del efecto local aplicado a cada paleta.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 bytes || Colores resultantes en formato de SNES, con 2 bytes por color. Las variantes <code>AndMergeDefault</code> escriben aquí.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> / <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 byte cada una || Cada bit indica si ya se preparó la base RGB de una paleta de fondo o de sprites.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> / <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 byte cada una || Lo mismo para las bases HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> / <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 byte cada una || Cada bit indica si ya hay un resultado del efecto para esa paleta.
|-
| <code>DX_PPU_CGRAM_LastPlayerPal</code> || 2 bytes || Dirección de la última paleta del jugador procesada. El sistema la compara para detectar cambios.
|}

Escribir colores en una copia de RAM no los envía inmediatamente a CGRAM. Utiliza las rutinas de paleta o una transferencia para actualizar lo que se muestra en pantalla. Los indicadores de bases y efectos preparados los administra el sistema; no es necesario borrarlos antes de cada llamada.

==== Color fijo y primer color de la paleta ====

El color fijo es el color que SNES puede utilizar para efectos como sumas y restas de color. El color 0,0 es la primera entrada de CGRAM. Dynamic Xtreme permite aplicar el efecto global a ambos por separado.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 byte || Activa la participación en el efecto global: bit <code>$01</code> para el color fijo y bit <code>$02</code> para el color 0,0. <code>$03</code> permite ambos.
|-
| <code>DX_PPU_ColorEffect_BaseLoaded</code> || 1 byte || Indica si se guardaron sus colores originales. Utiliza un bit por destino: <code>$01</code> y <code>$02</code>.
|-
| <code>DX_PPU_ColorEffect_RGBBaseLoaded</code> / <code>DX_PPU_ColorEffect_HSLBaseLoaded</code> || 1 byte cada una || Indican si sus colores ya se prepararon en RGB o HSL, con los mismos bits.
|-
| <code>DX_PPU_FixedColor_Mirror</code> || 2 bytes || Copia del color fijo que utiliza la actualización habitual del juego.
|-
| <code>DX_PPU_FixedColor_Base</code> || 2 bytes || Color fijo original, antes de los efectos.
|-
| <code>DX_PPU_FixedColor_RGBBase</code> / <code>DX_PPU_FixedColor_HSLBase</code> || 3 bytes cada una || Color fijo original separado en RGB o HSL.
|-
| <code>DX_PPU_FixedColor_Result</code> || 2 bytes || Color fijo calculado después del efecto.
|-
| <code>DX_PPU_FixedColor_LastGlobalEffectID</code> || 2 bytes || Último efecto global calculado para el color fijo.
|-
| <code>DX_PPU_PaletteColor00_Base</code> || 2 bytes || Color 0,0 original.
|-
| <code>DX_PPU_PaletteColor00_RGBBase</code> / <code>DX_PPU_PaletteColor00_HSLBase</code> || 3 bytes cada una || Color 0,0 original separado en RGB o HSL.
|-
| <code>DX_PPU_PaletteColor00_Result</code> || 2 bytes || Color 0,0 que se quiere mostrar.
|-
| <code>DX_PPU_PaletteColor00_LastGlobalEffectID</code> || 2 bytes || Último efecto global calculado para el color 0,0.
|-
| <code>DX_PPU_PaletteColor00_Update</code> || 1 byte || Un valor distinto de 0 solicita copiar <code>Result</code> al color 0,0 durante NMI. Después de copiarlo, el sistema vuelve a poner esta variable en 0.
|}

==== Transferencias pendientes ====

Estas variables guardan las copias que se realizarán durante NMI. Las macros de la sección PPU las rellenan por ti. Cada copia necesita un origen, un destino y una cantidad de bytes.

{| class="wikitable"
! Variable !! Contenido
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || Cantidad de copias de gráficos pendientes, en 1 byte.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || Cantidad de bytes de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || Destino de cada copia en VRAM, en valores de 2 bytes.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || Dirección de origen de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || Banco de origen de cada copia. La tabla reserva 2 bytes por entrada.
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || Cantidad de copias de colores pendientes, en 1 byte.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || Cantidad de bytes de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || Primer color de destino de cada copia, en valores de 1 byte.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || Dirección de origen de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || Banco de origen de cada copia.
|}

==== Jugador y Yoshi ====

Estas variables permiten cambiar de dónde se obtienen los gráficos y colores del jugador y los gráficos de Yoshi. Los archivos gráficos deben conservar la organización que esperan las rutinas del juego.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Dynamic_Player_GFX_Enable</code> || 1 byte || 0 desactiva la carga de gráficos mediante este sistema; un valor distinto de 0 la activa.
|-
| <code>DX_Dynamic_Player_GFX_Addr</code> || 2 bytes || Dirección de inicio de los gráficos del jugador dentro del banco indicado.
|-
| <code>DX_Dynamic_Player_GFX_BNK</code> || 2 bytes reservados || Banco de origen de los gráficos del jugador. El banco se indica en el byte bajo.
|-
| <code>DX_Dynamic_Player_Palette_Enable</code> || 1 byte || 0 desactiva el manejo de paleta del jugador mediante este sistema; un valor distinto de 0 lo activa.
|-
| <code>DX_Dynamic_Player_Palette_Addr</code> || 2 bytes || Dirección de origen de la paleta del jugador.
|-
| <code>DX_Dynamic_Player_Palette_BNK</code> || 1 byte || Banco de la paleta. Cuando es 0, la rutina toma la dirección de paleta que utiliza el juego.
|-
| <code>DX_Dynamic_Player_CustomPlayer</code> / <code>DX_Dynamic_Player_LastCustomPlayer</code> || 1 byte cada una || Variables reservadas para identificar al jugador personalizado y el anterior. La inicialización las pone en 0 y <code>$FF</code>; actualmente no seleccionan por sí solas los gráficos de un personaje.
|-
| <code>DX_Dynamic_Yoshi_VRAMEnable</code> || 1 byte || 0 desactiva la carga de gráficos de Yoshi mediante este sistema; un valor distinto de 0 la activa.
|-
| <code>DX_Dynamic_Yoshi_Addr</code> || 2 bytes || Dirección de inicio de los gráficos de Yoshi dentro de su banco.
|-
| <code>DX_Dynamic_Yoshi_BNK</code> || 1 byte || Banco de origen de los gráficos de Yoshi.
|}

==== Dibujo y variables de sprites ====

<code>DX_Drawing_InitialIndexHighPriority</code> y <code>DX_Drawing_InitialIndexLowPriority</code> ocupan 1 byte cada una y llevan la cuenta de las posiciones disponibles para dibujar sprites de prioridad alta o baja. <code>DX_Drawing_OAMMap</code> ocupa 128 bytes y ayuda a organizar los tiles dibujados. Estas variables se utilizan en la versión LoROM; el dibujo en SA-1 utiliza su manejo correspondiente.

Las variables individuales de sprites se definen en <code>DynamicXSpritesTables.asm</code>. Los archivos <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code> y <code>ExtendedSpriteDefines.asm</code> permiten utilizar los mismos nombres para los tres tipos:

{| class="wikitable"
! Nombre para el sprite !! Qué guarda
|-
| <code>!PoseIndex,x</code> || Pose que se quiere mostrar.
|-
| <code>!LastPoseIndex,x</code> || Última pose que se consiguió y puede dibujarse. Se inicia en <code>$FF</code>.
|-
| <code>!LastPoseHashIndex,x</code> || Entrada donde el sistema tiene registrada la ubicación de sus gráficos. Se inicia en <code>$FF</code>.
|-
| <code>!GlobalFlip,x</code> / <code>!LocalFlip,x</code> / <code>!LastFlip,x</code> || Volteo general, volteo adicional de la pose y volteo que se utiliza para dibujar.
|-
| <code>!Palette,x</code> || Paleta asignada: <code>$00</code> para la 8, <code>$02</code> para la 9, y así hasta <code>$0E</code> para la F. Se inicia en <code>$FF</code> cuando se utiliza asignación dinámica.
|-
| <code>!PaletteOption,x</code> || Opciones <code>EPPP----</code>: efecto global y elección de paleta o grupo de paletas.
|-
| <code>!PaletteAssignmentOption,x</code> || Modo de asignación: automático, manual o manual sin cargar colores.
|-
| <code>!Version,x</code> / <code>!LastVersion,x</code> || Variante del sprite y última variante procesada al manejar su paleta. <code>!LastVersion</code> se inicia en <code>$FF</code>.
|-
| <code>!RenderXDistanceOutOfScreen,x</code> / <code>!RenderYDistanceOutOfScreen,x</code> || Distancias que permiten seguir dibujando el sprite cuando su posición está fuera de la pantalla, pero alguna parte de su pose todavía puede verse.
|-
| <code>!SafeFrameLowByte,x</code> / <code>!SafeFrameHighByte,x</code> || Último frame en que se intentó solicitar una pose, para evitar repetir el trabajo durante el mismo frame.
|-
| <code>!AnimationIndex,x</code> / <code>!AnimationPoseIndex,x</code> / <code>!AnimationTimer,x</code> || Variables disponibles para llevar la cuenta de la animación, su paso actual y su temporizador. El código del recurso decide cómo utilizarlas.
|-
| <code>!State,x</code> || Variable para el estado o comportamiento del recurso.
|}

Cada variable de esta tabla ocupa 1 byte por sprite. Hay <code>!MaxSprites</code> entradas para normales, 20 para cluster y 10 para extended. No utilices <code>!MaxSprites</code> como cantidad de entradas de cluster o extended.

<code>DX_FreeRams</code> y <code>DX_FreeRams2</code> marcan el comienzo de las áreas donde se colocan estas tablas. No representan memoria libre para guardar datos propios encima de las variables de sprites.

=== Defines fijos ===

Estos nombres representan configuraciones y direcciones conocidas. No son variables que cambian durante el juego.

==== Compatibilidad con LoROM y SA-1 ====

<code>DXDefines.asm</code> detecta el tipo de ROM y elige los valores correspondientes. Utiliza estos nombres para que tu código funcione en ambos casos.

{| class="wikitable"
! Define !! LoROM !! SA-1 !! Uso
|-
| <code>!sa1</code> || 0 || 1 || Permite elegir código distinto según el tipo de ROM.
|-
| <code>!dp</code> || <code>$0000</code> || <code>$3000</code> || Ajuste de las direcciones de página directa.
|-
| <code>!addr</code> || <code>$0000</code> || <code>$6000</code> || Ajuste de las direcciones RAM que lo requieren, por ejemplo <code>$0100|!addr</code>.
|-
| <code>!rom</code> || <code>$800000</code> || <code>$000000</code> || Ajuste utilizado al acceder a direcciones del código original del juego.
|-
| <code>!MaxSprites</code> || <code>$0C</code> (12) || <code>$16</code> (22) || Cantidad de posiciones de sprites normales.
|-
| <code>!MultiplicationResult</code> || <code>$4216</code> || <code>$2306</code> || Dirección donde se lee el resultado de una multiplicación.
|-
| <code>!DivisionResult</code> || <code>$4214</code> || <code>$2306</code> || Dirección donde se lee el cociente de una división.
|-
| <code>!RemainderResult</code> || <code>$4216</code> || <code>$2308</code> || Dirección donde se lee el resto de una división.
|}

Otros defines utilizados para colocar las variables son <code>!normalBnk</code>, <code>!PalCopyBNK</code>, <code>!Variables</code> y <code>!Variables2</code>. Normalmente basta con utilizar el nombre de cada variable <code>DX_...</code>, sin calcular su dirección a partir de estos valores.

==== Direcciones de gráficos en VRAM ====

Estos defines permiten indicar el destino de una transferencia sin escribir su dirección numérica. Cada familia tiene líneas de 0 a 7; sustituye N por el número de línea.

{| class="wikitable"
! Familia !! Línea 0 !! Avance por línea !! Ejemplo
|-
| <code>!FG1LineN</code> || <code>$0000</code> || <code>$0100</code> || <code>!FG1Line1 = $0100</code>
|-
| <code>!FG2LineN</code> || <code>$0800</code> || <code>$0100</code> || <code>!FG2Line1 = $0900</code>
|-
| <code>!BG1LineN</code> || <code>$1000</code> || <code>$0100</code> || <code>!BG1Line1 = $1100</code>
|-
| <code>!FG3LineN</code> || <code>$1800</code> || <code>$0100</code> || <code>!FG3Line1 = $1900</code>
|-
| <code>!BG2LineN</code> || <code>$2000</code> || <code>$0100</code> || <code>!BG2Line1 = $2100</code>
|-
| <code>!BG3LineN</code> || <code>$2800</code> || <code>$0100</code> || <code>!BG3Line1 = $2900</code>
|-
| <code>!LG1LineN</code> a <code>!LG4LineN</code> || <code>$4000</code>, <code>$4400</code>, <code>$4800</code>, <code>$4C00</code> || <code>$0080</code> || <code>!LG1Line1 = $4080</code>
|-
| <code>!SP1LineN</code> a <code>!SP4LineN</code> || <code>$6000</code>, <code>$6800</code>, <code>$7000</code>, <code>$7800</code> || <code>$0100</code> || <code>!SP4Line1 = $7900</code>
|}

<code>!Layer1Tilemap = $3000</code> y <code>!Layer2Tilemap = $3800</code> indican las direcciones habituales de los mapas de tiles de Layer 1 y Layer 2. Las direcciones de VRAM de esta sección se expresan en palabras de 2 bytes, como las que reciben las macros de transferencia.

==== Configuraciones de espacio para poses dinámicas ====

Los defines <code>!DynamicSpaceConfig...</code> se entregan a <code>!DynamicPoseSpaceConfig</code>. El nombre indica qué áreas de gráficos se permiten utilizar. <code>FirstHalf</code> significa primera mitad y <code>SecondHalf</code>, segunda mitad. Los nombres con <code>WithPlayer</code> o <code>WithDSX</code> corresponden a las configuraciones previstas para esos casos.

{| class="wikitable"
! Valor !! Define
|-
| <code>$00</code> || <code>!DynamicSpaceConfigSecondHalfSSP4</code>
|-
| <code>$01</code> || <code>!DynamicSpaceConfigSP4</code>
|-
| <code>$02</code> || <code>!DynamicSpaceConfigSecondHalfSP3</code>
|-
| <code>$03</code> || <code>!DynamicSpaceConfigFirstHalfSP3</code>
|-
| <code>$04</code> || <code>!DynamicSpaceConfigSP3</code>
|-
| <code>$05</code> || <code>!DynamicSpaceConfigSecondHalfSP2</code>
|-
| <code>$06</code> || <code>!DynamicSpaceConfigFirstHalfSP2</code>
|-
| <code>$07</code> || <code>!DynamicSpaceConfigSP2</code>
|-
| <code>$08</code> || <code>!DynamicSpaceConfigSecondHalfSP1</code>
|-
| <code>$09</code> || <code>!DynamicSpaceConfigFirstHalfSP1</code>
|-
| <code>$0A</code> || <code>!DynamicSpaceConfigSP1</code>
|-
| <code>$0B</code> || <code>!DynamicSpaceConfigFirstHalfSP1WithPlayer</code>
|-
| <code>$0C</code> || <code>!DynamicSpaceConfigSP11WithPlayer</code>
|-
| <code>$0D</code> || <code>!DynamicSpaceConfigSecondHalfSP3ndSP4</code>
|-
| <code>$0E</code> || <code>!DynamicSpaceConfigSP34</code>
|-
| <code>$0F</code> || <code>!DynamicSpaceConfigSecondHalfSP2andSP34</code>
|-
| <code>$10</code> || <code>!DynamicSpaceConfigSP234</code>
|-
| <code>$11</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234</code>
|-
| <code>$12</code> || <code>!DynamicSpaceConfigSP1234</code>
|-
| <code>$13</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithPlayer</code>
|-
| <code>$14</code> || <code>!DynamicSpaceConfigSP1234WithPlayer</code>
|-
| <code>$15</code> || <code>!DynamicSpaceConfigSecondHalfSP3ndSP4WithDSX</code>
|-
| <code>$16</code> || <code>!DynamicSpaceConfigSP34WithDSX</code>
|-
| <code>$17</code> || <code>!DynamicSpaceConfigSecondHalfSP2andSP34WithDSX</code>
|-
| <code>$18</code> || <code>!DynamicSpaceConfigSP234WithDSX</code>
|-
| <code>$19</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithDSX</code>
|-
| <code>$1A</code> || <code>!DynamicSpaceConfigSP1234WithDSX</code>
|-
| <code>$1B</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithPlayerAndDSX</code>
|-
| <code>$1C</code> || <code>!DynamicSpaceConfigSP1234WithPlayerAndDSX</code>
|}

Los nombres de esta tabla se escriben exactamente como aparecen en <code>DXDefines.asm</code>, incluidos nombres como <code>SecondHalfSSP4</code> y <code>SP11WithPlayer</code>.

==== Otras constantes ====

{| class="wikitable"
! Define !! Valor o uso
|-
| <code>!AN2Buffer1</code> / <code>!AN2Buffer2</code> || Direcciones <code>$7EC100</code> y <code>$7EAD00</code> utilizadas para datos de animación.
|-
| <code>!GFX32Buffer</code> || <code>$7E2000</code>, dirección del buffer habitual de GFX32.
|-
| <code>!PlayerPaletteColor2To5</code> || <code>$00B280</code>, datos de los colores 2-5 de la paleta del jugador.
|-
| <code>!PlayerBasePalette</code> || <code>$00B2C8</code>, datos de la paleta base del jugador.
|-
| <code>!VRAMTransferSize</code> / <code>!CGRAMTransferSize</code> || Ambos valen 64 en la plantilla actual. Se utilizan para reservar las tablas de transferencias; no representan el límite de bytes que se cargan por frame.
|}

Las opciones de instalación, como <code>!DynamicPoses</code>, <code>!DrawingSystem</code>, <code>!GraphicsChange</code>, <code>!PalettesChange</code>, <code>!PalettesEffects</code>, <code>!PlayerFeatures</code> y <code>!YoshiFeatures</code>, se incluyen desde <code>Options.asm</code>. Sus valores indican qué funciones se instalaron; no se cambian durante el juego.

=== Defines generados ===

Dynamic Xtreme crea estos defines al instalar los recursos y los añade a <code>DXDefines.asm</code>. Utiliza sus nombres en lugar de copiar los valores numéricos, porque los IDs, direcciones y tamaños pueden cambiar cuando se agregan o modifican recursos.

Los nombres se normalizan en PascalCase: se eliminan espacios, guiones bajos, guiones y otros separadores, y se pone en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_sprite</code>, <code>my-sprite</code> y <code>my sprite</code> se convierten en <code>MySprite</code>. Se conserva el resto de las mayúsculas y minúsculas que ya tenía el nombre. Ante una duda, copia el nombre exacto de <code>DXDefines.asm</code>.

==== Poses dinámicas y poses de dibujo ====

{| class="wikitable"
! Familia o ejemplo !! Qué representa
|-
| <code>!DynamicPoseIDMySprite000</code> || ID de unos gráficos de pose declarados en el DynamicInfo. Se utiliza para solicitar su carga con <code>!Upload</code>.
|-
| <code>!DynamicPoseMySprite000</code> || Dirección ROM de esos gráficos.
|-
| <code>!DynamicPoseMySprite000Size</code> || Tamaño de esos gráficos en bytes.
|-
| <code>!PoseIDMySprite_Frame0</code> || ID de una pose del DrawInfo. Se utiliza para dibujarla con <code>!DXDraw</code> o <code>DrawStatic</code>.
|-
| <code>!RenderBoxXDistanceOutOfScreenMySprite</code> || Distancia horizontal calculada desde el DrawInfo para saber cuándo el sprite deja de verse.
|-
| <code>!RenderBoxYDistanceOutOfScreenMySprite</code> || Distancia vertical calculada desde el DrawInfo para la misma comprobación.
|}

El ID dinámico elige qué gráficos cargar; el ID de dibujo elige cómo colocar los tiles para formar la pose. Son valores distintos. Un define <code>!DynamicPoseID...</code> no se utiliza en lugar de un <code>!PoseID...</code>.

==== Paletas y efectos ====

{| class="wikitable"
! Familia o ejemplo !! Qué representa
|-
| <code>!PaletteIDMyPalette</code> || ID de una paleta declarada desde el DynamicInfo.
|-
| <code>!PaletteMyPalette</code> || Dirección ROM de sus colores.
|-
| <code>!PaletteMyPaletteSize</code> || Tamaño de la paleta en bytes.
|-
| <code>!MySpritePaletteTableOffset</code> || Indica dónde comienza la lista de paletas de ese DynamicInfo. Se entrega a <code>!PaletteAssignment</code> y a sus variantes.
|-
| <code>!PaletteEffectIDMyEffect0</code> || ID de un efecto de <code>my_effect.paleffect</code>. El número final identifica el efecto dentro del archivo; los IDs globales comienzan en 1.
|-
| <code>!PaletteMyTargetRGB</code> / <code>!PaletteMyTargetHSL</code> || Dirección ROM de una paleta de destino convertida para una transición RGB o HSL. Se genera cuando un efecto necesita esa paleta.
|-
| <code>!PaletteMyTargetRGBSize</code> / <code>!PaletteMyTargetHSLSize</code> || Tamaño en bytes de esas paletas convertidas.
|}

Los nombres de los ejemplos usan la misma normalización: <code>my_palette</code> pasa a <code>MyPalette</code> y <code>my_effect</code> a <code>MyEffect</code>. Los defines se generan durante la instalación y quedan en <code>DXDefines.asm</code>.

==== Recursos generales y buffers ====

{| class="wikitable"
! Familia o ejemplo !! Qué representa
|-
| <code>!ResourceIDMyResource</code> || ID de un recurso general del DynamicInfo.
|-
| <code>!ResourceMyResource</code> || Dirección ROM de ese recurso.
|-
| <code>!ResourceMyResourceSize</code> || Tamaño del recurso en bytes.
|-
| <code>!BufferIDMyBuffer</code> || ID de un buffer insertado por la herramienta.
|-
| <code>!BufferMyBuffer</code> || Dirección del buffer insertado en la ROM; no es una variable temporal de RAM.
|-
| <code>!BufferMyBufferSize</code> || Tamaño del buffer en bytes.
|}

Los nombres dependen de los recursos instalados. Se normalizan del mismo modo: <code>my_resource</code> pasa a <code>MyResource</code>. Consulta <code>DXDefines.asm</code> para ver los nombres y valores de tu instalación.

==== Cantidades y tablas generadas ====

Estos defines permiten consultar las cantidades y las tablas creadas al instalar los recursos. Para un sprite normal suele bastar con utilizar los IDs individuales de las tablas anteriores.

{| class="wikitable"
! Define !! Qué representa
|-
| <code>!NumberOfDynamicPoses</code> / <code>!NumberOfPoses</code> || Cantidad de poses dinámicas y de poses de dibujo instaladas, respectivamente.
|-
| <code>!NumberOfPalettes</code> / <code>!NumberOfResources</code> / <code>!NumberOfBuffers</code> || Cantidad de paletas normales, recursos generales y buffers insertados.
|-
| <code>!NumberOfPaletteEffects</code> || Valor usado para dimensionar las tablas de efectos. La generación incluye el espacio del ID 0; no lo interpretes como cantidad de efectos escritos en un archivo <code>*.paleffect</code>.
|-
| <code>!PaletteTableSize</code> || Cantidad total de entradas en las listas de paletas de los DynamicInfo.
|-
| <code>!PaletteIDTables</code> || Dirección de la tabla de IDs de esas listas de paletas.
|-
| <code>!PaletteAddrTables</code> || Dirección de la tabla con las direcciones ROM de sus colores.
|-
| <code>!PaletteEffectsTypes</code> || Tabla con el tipo de cada efecto instalado.
|-
| <code>!PaletteEffectsChannels1</code>, <code>!PaletteEffectsChannels2</code>, <code>!PaletteEffectsChannels3</code> || Tablas con los valores de color de cada efecto.
|-
| <code>!PaletteEffectsRatios1</code>, <code>!PaletteEffectsRatios2</code>, <code>!PaletteEffectsRatios3</code> || Tablas con los ratios que controlan cuánto se aplica cada cambio.
|-
| <code>!BufferTable</code>, <code>!PaletteTables</code>, <code>!PaletteEffectsTable</code> || Direcciones de las tablas que el parche publica para esos datos.
|}

=== Defines de rutinas ===

Estos defines representan llamadas del sistema, no variables para guardar datos. La tabla sirve para encontrarlas; su uso se explica en las secciones de rutinas y macros.

{| class="wikitable"
! Define o familia !! Uso
|-
| <code>!AllowedGameMode</code> || Comprueba si el modo de juego actual permite procesar las operaciones correspondientes.
|-
| <code>!DynamicPoseSpaceConfig</code> || Elige las partes de VRAM disponibles para poses dinámicas.
|-
| <code>!TakeDynamicRequest</code> || Solicita una pose por su ID.
|-
| <code>!DynamicRoutine</code> || Prepara las copias de gráficos de una pose a VRAM.
|-
| <code>!SetPropertyAndOffset</code> || Obtiene la ubicación y propiedades de los gráficos de una pose dinámica para dibujarla.
|-
| <code>!Draw</code> / <code>!Draw_Return</code> || Entrada y punto de retorno utilizados por las rutinas de dibujo.
|-
| <code>!RemapOamTile</code> || Ajusta el número de tile para utilizar la ubicación real de los gráficos dinámicos.
|-
| <code>!IsValid</code>, <code>!XIsValid</code>, <code>!YIsValid</code> || Comprobaciones utilizadas por el dibujo para decidir si un tile puede mostrarse.
|-
| <code>!AssignPalette</code> || Selecciona el destino de una paleta según el modo de asignación.
|-
| <code>!LoadPaletteOnBuffer</code> || Carga datos de paleta en un espacio de trabajo para procesarlos.
|-
| <code>!SetRGBBase</code> / <code>!SetHSLBase</code> || Prepara los colores para calcular efectos RGB o HSL.
|-
| <code>!RGBToHSL</code> / <code>!HSLToRGB</code> || Convierte entre ambos sistemas de color.
|-
| <code>!RGBMerge</code> || Convierte colores RGB separados al formato de paleta de SNES.
|-
| <code>!Mix...</code> / <code>!MixAndMerge...</code> || Aplica cambios a uno o varios componentes del color.
|-
| <code>!PalTransitionRGB</code> / <code>!PalTransitionHSL</code> || Calcula el cambio de una paleta a otra.
|-
| <code>!PalTransitionAndMergeRGB</code> / <code>!PalTransitionAndMergeHSL</code> || Calcula la transición y deja el resultado en formato de SNES.
|-
| <code>!DoEffect</code> / <code>!DoEffectAndMerge</code> || Aplica un efecto mediante su ID.
|-
| <code>!PalFunctionRGB</code>, <code>!PalFunctionHSL</code> y variantes <code>AndMerge</code> || Nombres reservados para funciones de color que todavía no están implementadas.
|}

<code>!Routines</code> es la dirección de la tabla desde la que se obtienen estas llamadas. No necesitas calcular sus posiciones para usar los defines publicados.

== Estado del CPU y memoria temporal ==

Cada llamada necesita que los registros tengan el tamaño indicado en su entrada. Un registro puede terminar en 8 bits y aun así haber perdido su valor anterior: '''tamaño y contenido son cosas distintas'''.

Estas reglas se aplican a las llamadas de este artículo, salvo las excepciones indicadas en cada entrada:

* Ejecuta el código en modo nativo, con el modo decimal desactivado. Las operaciones matemáticas del sistema utilizan números binarios.
* '''Direct page D:''' <code>$0000</code> en LoROM y <code>$3000</code> en el contexto habitual de SA-1 Pack. Las direcciones cortas como <code>$00</code> se interpretan respecto de esa base. Las llamadas no preparan ni cambian D por ti.
* '''Banco de datos DBR:''' debe permitir acceder a los espejos de RAM y a los registros hardware utilizados por la llamada. El contexto habitual usa bancos con esos espejos, como <code>$00-$3F</code> o <code>$80-$BF</code>. Si entregas un operando que lee una tabla mediante una dirección de 16 bits, DBR también debe permitir leer esa tabla. Un puntero de 24 bits lleva su propio banco. <code>DynamicRoutine</code> tiene un requisito específico de DBR, explicado en su entrada.
* Las llamadas conservan DBR y D. Algunas cambian DBR temporalmente y lo restauran antes de retornar. Esto no significa que cualquier banco de entrada sea válido.
* '''Flags:''' utiliza como resultado únicamente los que se indiquen expresamente. No supongas que N, Z, V o carry conservan su valor anterior. Los cambios de tamaño de A y X/Y se indican por llamada.
* '''Memoria temporal:''' las scratch indicadas pueden sobrescribirse tanto en éxito como en fallo. Guarda fuera de ellas cualquier dato que necesites después. Las salidas solo son válidas en las condiciones descritas en cada entrada.
* '''Pila:''' las llamadas retiran los datos temporales que ellas mismas apilan. Tu código debe emparejar sus propios pushes y pulls con el mismo tamaño de registro, y respetar el retorno de la rutina o macro.

Para conservar un registro, guárdalo antes de la llamada y recupéralo después con el mismo tamaño. Si necesitas comprobar el carry devuelto, hazlo antes de ejecutar otra operación que lo modifique; restaurar P mediante <code>PLP</code> también reemplaza ese carry.

== Rutinas para sprites ==

Estas rutinas permiten comprobar si un sprite debe dibujarse en pantalla, cargar sus gráficos y manejar sus paletas. Antes de utilizarlas, incluye el archivo de defines correspondiente: <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code> o <code>ExtendedSpriteDefines.asm</code>. La ruta del include es relativa al archivo ASM del sprite.

Los requisitos de DBR, D, flags y pila se explican en [[#Estado del CPU y memoria temporal|Estado del CPU y memoria temporal]]. La tabla siguiente distingue el tamaño de los registros de los valores que conservan.

Para usar llamadas como <code>!RenderBox</code> o <code>!Upload</code>, escribe su nombre directamente, como muestran los ejemplos. No añadas <code>JSR</code> ni <code>JSL</code> delante. Salvo que se indique lo contrario, X debe contener el número del slot que ocupa el sprite.

'''Registros y scratch de las llamadas para sprites'''

Entra con X e Y en modo de 8 bits. El tamaño de A depende de la llamada:

{| class="wikitable"
! Llamada !! A al entrar !! Registros al volver !! Scratch que puede sobrescribir
|-
| <code>!RenderBox</code>
| 8 bits.
| A cambia y queda en 8 bits. X e Y conservan su valor y tamaño.
| No utiliza scratch; modifica las tablas de Dynamic Xtreme descritas en su entrada.
|-
| <code>!PaletteAssignment</code> y <code>!PaletteAssignmentNoUpload</code>
| 16 bits con <code>PalettesChange</code> habilitado; 8 bits si está deshabilitado, sin utilizar el offset de tabla.
| A e Y pueden cambiar. X vuelve a cargarse desde <code>!SpriteIndex</code> cuando se utiliza para el trabajo interno. La variante sin carga devuelve información en Y. Los tres quedan en 8 bits.
| <code>$00-$0F</code>, <code>$65-$67</code>, <code>$D5</code>, según el camino utilizado. Con efectos, también puede utilizar los temporales de efectos indicados más abajo.
|-
| <code>!Upload</code> y <code>!UploadWithoutPoseOffset</code>
| 16 bits.
| A e Y pueden cambiar. X se recupera desde <code>!SpriteIndex</code>. Los tres quedan en 8 bits.
| <code>$00-$0F</code> y <code>$47-$51</code> cuando necesita preparar una carga nueva.
|-
| <code>!DXDraw</code> y <code>!DXDrawWithOffset</code>
| 16 bits.
| A e Y pueden cambiar. Si dibuja, X se recupera desde <code>!SpriteIndex</code>; si no hay pose válida, conserva el X de entrada. Los tres quedan en 8 bits.
| <code>$00-$0F</code>, <code>$45-$4F</code> y <code>$8A</code>. Con desplazamiento adicional, también <code>$8B-$8C</code>.
|-
| <code>!ReplacePalette</code>
| 8 bits.
| A e Y pueden cambiar. X se recupera desde <code>!SpriteIndex</code>. Los tres quedan en 8 bits.
| <code>$00-$01</code> y los temporales utilizados por la carga de colores; también los de efectos cuando corresponde.
|-
| <code>!ConcatenateRGBPaletteEffectToGlobal</code> y variante HSL
| 16 bits.
| A e Y pueden cambiar. Aunque X recibe una paleta al entrar, al volver contiene <code>!SpriteIndex</code>. Los tres quedan en 8 bits.
| Los temporales de efectos, <code>$05-$06</code> y <code>$F0-$F3</code>.
|}

PIXI mantiene <code>!SpriteIndex</code> como el índice del sprite actual. Si cambias X temporalmente, las llamadas que recuperan ese índice no conservan necesariamente el X que tú les entregaste. En particular, después de concatenar un efecto, X vuelve a identificar al sprite, no a su paleta. Los aliases de PIXI realizan la llamada y después continúan en la instrucción siguiente; el <code>RTS</code> de los ejemplos pertenece a la rutina del sprite.

=== RenderBox ===

<code>!RenderBox</code> comprueba si el sprite está en pantalla o lo bastante cerca de sus bordes como para seguir dibujándose. Se utiliza al comienzo de la rutina principal para decidir si ejecutar solo su lógica (short routine) o también cargar sus gráficos, manejar su paleta y dibujarlo (long routine).

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalRenderBox()</code>.
* Cluster sprite: <code>%DXClusterRenderBox()</code>.
* Extended sprite: <code>%DXExtendedRenderBox()</code>.

'''Entradas'''

* X: índice del sprite.
* <code>!RenderXDistanceOutOfScreen,x</code> y <code>!RenderYDistanceOutOfScreen,x</code>: distancias horizontal y vertical permitidas fuera de la pantalla.

'''Resultado'''

* Carry activado: el sprite está en pantalla o dentro de la distancia permitida fuera de sus bordes; se debe ejecutar la long routine.
* Carry desactivado: el sprite está demasiado lejos de la pantalla para dibujarse; se debe ejecutar la short routine.

Cuando el sprite está demasiado lejos, establece <code>!Palette</code>, <code>!LastVersion</code>, <code>!LastPoseIndex</code> y <code>!LastPoseHashIndex</code> en <code>$FF</code>. Esto indica que deberá volver a obtener su paleta y su pose cuando se acerque a la pantalla. También guarda en <code>!LastFlip</code> el volteo que resulta de combinar <code>!GlobalFlip</code> y <code>!LocalFlip</code>. En sprites normales actualiza además las variables que indican si está fuera de pantalla horizontal o verticalmente.

'''Ejemplo'''

<pre>
print "INIT ",pc
LDA.b #!RenderBoxXDistanceOutOfScreenMySprite
STA !RenderXDistanceOutOfScreen,x
LDA.b #!RenderBoxYDistanceOutOfScreenMySprite
STA !RenderYDistanceOutOfScreen,x
; Aquí va el resto de la inicialización del sprite
RTL

SpriteCode:
!RenderBox
BCS .LongRoutine

.ShortRoutine
LDA #$00
%SubOffScreen()
; Aquí va la lógica de tu sprite
RTS

.LongRoutine
; Aquí van el manejo de paletas, poses y dibujo
; y la lógica de tu sprite
RTS
</pre>

La llamada a <code>%SubOffScreen()</code> del ejemplo corresponde a sprites normales y recibe en A un valor entre 0 y 7 para seleccionar la configuración de eliminación fuera de pantalla. El ejemplo utiliza 0, el valor habitual. Se recomienda utilizarla en la short routine; dentro de la long routine resulta redundante.

Los defines <code>!RenderBoxXDistanceOutOfScreenMySprite</code> y <code>!RenderBoxYDistanceOutOfScreenMySprite</code> se generan desde el DrawInfo y se guardan en <code>DXDefines.asm</code>. El nombre del recurso se normaliza en PascalCase: se eliminan separadores como espacios, guiones bajos y guiones, y se escribe en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_sprite</code> se convierte en <code>MySprite</code>. Si el sprite utiliza varios DrawInfo, utiliza la mayor distancia horizontal y la mayor distancia vertical entre ellos.

=== PaletteAssignment ===

<code>!PaletteAssignment</code> selecciona una paleta del DynamicInfo usando <code>!Version,x</code>, le asigna una de las paletas de sprites 8-F y carga sus colores cuando hace falta. Si el sprite ya tiene esa paleta, mantiene su temporizador de uso en 2 para evitar que otro recurso la reemplace. Debe llamarse en cada frame de la long routine; esto no significa que los colores vuelvan a cargarse cada vez.

Si el bit <code>E</code> de <code>!PaletteOption,x</code> está activado (<code>$80</code>), también procesa los efectos globales de paleta correspondientes. Si está desactivado, la paleta queda excluida del efecto global.

'''Cómo se elige la paleta'''

<code>!Version,x</code> selecciona una paleta de la lista del DynamicInfo: 0 elige la primera, 1 la segunda, etc. Por ejemplo, si la lista contiene una paleta roja y otra azul, las versiones 0 y 1 seleccionan esos colores. El sprite también puede usar esta variable para cambiar su comportamiento; la rutina de paletas solo la utiliza para elegir los colores.

<code>!PaletteOption,x</code> indica qué paleta de sprites se permite utilizar y si sus colores reciben el efecto global. Su formato es <code>EPPP----</code>:

* <code>E</code>: 0 excluye la paleta del efecto global; 1 permite aplicarlo.
* <code>PPP</code>: con asignación manual, selecciona una paleta entre 8 y F. <code>000</code> elige la 8, <code>001</code> la 9, y así hasta <code>111</code> para la F.
* Con asignación automática, <code>PPP = 000</code> permite buscar entre las ocho paletas. Un valor <code>0XX</code> distinto de <code>000</code> limita la búsqueda a las paletas 8-B; un valor <code>1XX</code> la limita a las C-F.
* Los cuatro bits bajos no se utilizan para estas opciones.

<code>!PaletteAssignmentOption,x</code> decide quién elige el destino y si se cargan colores. Su formato es <code>--AA----</code>:

* <code>AA = 00</code> (<code>$00</code>): automático. Dynamic Xtreme elige una de las paletas permitidas y carga los colores del DynamicInfo.
* <code>AA = 01</code> (<code>$10</code>): manual. Utiliza la paleta indicada en <code>PPP</code> y carga los colores del DynamicInfo.
* <code>AA = 10</code> (<code>$20</code>): manual sin carga. Utiliza la paleta indicada en <code>PPP</code> con los colores que ya tiene el nivel.

En sprites normales, <code>!PaletteOption,x</code> es <code>!ExtraByte1,x</code> y <code>!PaletteAssignmentOption,x</code> es <code>!ExtraProp2,x</code>. Lo habitual es usar el primer Extra Byte con formato <code>EPPPVVVV</code> y copiar sus cuatro bits bajos a <code>!Version,x</code> durante el INIT. Así se puede elegir la versión desde Lunar Magic. En cluster y extended, el código que crea el sprite debe establecer estas variables.

Por ejemplo, con asignación manual, <code>!PaletteOption,x = $A0</code> utiliza la paleta A y permite el efecto global. Si <code>!Version,x = 1</code>, carga en ella la segunda paleta de la lista del DynamicInfo.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalPaletteAssignment()</code>.
* Cluster sprite: <code>%DXClusterPaletteAssignment()</code>.
* Extended sprite: <code>%DXExtendedPaletteAssignment()</code>.

'''Entradas'''

* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> correspondiente al DynamicInfo que contiene las paletas.
* X: índice del sprite.
* <code>!Version,x</code>: índice de la paleta dentro de la tabla.
* <code>!LastVersion,x</code>: última versión procesada. Se compara con <code>!Version,x</code> para detectar cambios y debe inicializarse en <code>$FF</code>.
* <code>!PaletteOption,x</code>: selección de paleta y participación en el efecto global.
* <code>!PaletteAssignmentOption,x</code>: asignación automática, manual o manual sin carga.

'''Resultado'''

* Carry activado: el sprite puede dibujarse con la paleta asignada.
* Carry desactivado: el sprite todavía no tiene una paleta lista para dibujar.
* <code>!Palette,x</code>: paleta asignada, con valores de <code>$00</code> a <code>$0E</code> de dos en dos para las paletas 8-F.
* <code>!LastVersion,x</code>: se actualiza con <code>!Version,x</code> cuando se procesa la nueva asignación.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignment
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y se guarda en <code>DXDefines.asm</code>. El nombre del recurso se normaliza en PascalCase eliminando separadores y poniendo en mayúscula la inicial de cada palabra: <code>my_sprite</code> se convierte en <code>MySprite</code>.

=== PaletteAssignmentNoUpload ===

<code>!PaletteAssignmentNoUpload</code> elige la paleta igual que <code>!PaletteAssignment</code>, pero deja pendiente la carga de los colores. Se utiliza cuando primero necesitas modificar la paleta, por ejemplo aplicando un efecto local y combinándolo con el global. Si ya estaba asignada, mantiene su temporizador de uso en 2 para evitar que otro recurso la reemplace.

El bit <code>E</code> de <code>!PaletteOption,x</code> (<code>$80</code>) también determina si la paleta participa en los efectos globales. Esta variante prepara la asignación y la paleta base; la aplicación final de los efectos y la carga se completan mediante la rutina posterior, como <code>!ConcatenateRGBPaletteEffectToGlobal</code> o <code>!ConcatenateHSLPaletteEffectToGlobal</code>.

<code>!Version,x</code> elige la paleta del DynamicInfo: 0 para la primera, 1 para la segunda, etc. <code>!PaletteOption,x</code> utiliza <code>EPPP----</code>: E permite el efecto global y PPP selecciona la paleta 8-F en modo manual, o el grupo donde buscarla en modo automático. En automático, <code>000</code> permite todas, <code>0XX</code> distinto de cero permite 8-B y <code>1XX</code> permite C-F.

<code>!PaletteAssignmentOption,x</code> utiliza <code>--AA----</code>: <code>$00</code> elige el destino automáticamente, <code>$10</code> usa el indicado en PPP y <code>$20</code> utiliza los colores que ya tiene el nivel. Para preparar una paleta que después recibirá un efecto local, utiliza uno de los modos que toman los colores del DynamicInfo: automático o manual con carga.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalPaletteAssignmentNoUpload()</code>.
* Cluster sprite: <code>%DXClusterPaletteAssignmentNoUpload()</code>.
* Extended sprite: <code>%DXExtendedPaletteAssignmentNoUpload()</code>.

'''Entradas'''

* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> del DynamicInfo que contiene las paletas.
* X: índice del sprite.
* <code>!Version,x</code>, <code>!PaletteOption,x</code> y <code>!PaletteAssignmentOption,x</code>: mismas opciones que en <code>!PaletteAssignment</code>.
* <code>!LastVersion,x</code>: última versión procesada, utilizada para detectar cambios respecto de <code>!Version,x</code>. Debe inicializarse en <code>$FF</code>.

'''Resultado'''

* Carry activado: el sprite tiene una paleta asignada; desactivado si no pudo obtenerse.
* <code>!Palette,x</code>: paleta asignada.
* <code>!LastVersion,x</code>: se actualiza con <code>!Version,x</code> cuando se procesa la nueva asignación.
* <code>$00-$01</code>: número que identifica la paleta elegida del DynamicInfo, cuando se utiliza un modo que carga sus colores.
* <code>$02-$04</code>: dirección de la paleta base en ROM.
* Y = 1: se acaba de asignar la paleta y hay que calcular su efecto; Y = 0: no es necesario recalcularlo por una asignación nueva. Entrega este valor a la rutina de concatenación.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

; Aquí se prepara y concatena el efecto.
; Conserva Y y la dirección de $02-$04 para esa llamada.
.Return
RTS
</pre>

<code>$00-$01</code> dice qué paleta del DynamicInfo se eligió; <code>!Palette,x</code> dice cuál de las paletas 8-F utilizará el sprite para dibujarse. Los datos de <code>$00-$04</code> solo se preparan cuando la rutina lee la paleta del DynamicInfo. Si usas el modo manual sin carga, deshabilitaste los cambios de paleta o la llamada no se procesa en el modo de juego actual, no utilices esos datos como resultado de la llamada.

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase: <code>my_sprite</code> pasa a <code>MySprite</code>, eliminando los separadores.

=== Upload ===

<code>!Upload</code> consigue los gráficos de la pose que el sprite quiere mostrar. La pose se selecciona sumando <code>!PoseIndex,x</code> al ID dinámico recibido en A. Si sus gráficos ya están en VRAM, solo actualiza su registro de último uso para evitar que sean sobrescritos. Si todavía no están, solicita su carga. Debe llamarse en cada frame de la long routine.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalUpload()</code>.
* Cluster sprite: <code>%DXClusterUpload()</code>.
* Extended sprite: <code>%DXExtendedUpload()</code>.

'''Entradas'''

* A de 16 bits: ID dinámico base.
* X: índice del sprite.
* <code>!PoseIndex,x</code>: índice que se suma al ID base.
* <code>!GlobalFlip,x</code> y <code>!LocalFlip,x</code>: volteos que se combinarán para dibujar.

'''Resultado'''

* Carry activado: el sprite tiene una pose disponible para dibujar. Puede ser la solicitada o la anterior si todavía no fue posible cargar la nueva.
* Carry desactivado: el sprite todavía no tiene una pose disponible.
* <code>!LastPoseIndex,x</code>, <code>!LastPoseHashIndex,x</code> y <code>!LastFlip,x</code>: estado de la pose disponible para dibujar.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
!Upload
RTS
</pre>

<code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase: se eliminan separadores y se escribe en mayúscula la inicial de cada palabra, como <code>my_sprite</code> → <code>MySprite</code>.

=== UploadWithoutPoseOffset ===

<code>!UploadWithoutPoseOffset</code> solicita directamente el ID dinámico entregado en A, sin sumarle <code>!PoseIndex</code>. Como <code>!Upload</code>, reutiliza los gráficos si ya están en VRAM y puede seguir mostrando la pose anterior mientras no consiga cargar la nueva.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalUploadWithoutPoseOffset()</code>.
* Cluster sprite: <code>%DXClusterUploadWithoutPoseOffset()</code>.
* Extended sprite: existe <code>%DXExtendedUploadWithoutPoseOffset()</code>, pero actualmente <code>ExtendedSpriteDefines.asm</code> no publica el alias <code>!UploadWithoutPoseOffset</code>.

'''Entradas'''

* A de 16 bits: ID dinámico exacto.
* X: índice del sprite.
* <code>!GlobalFlip,x</code> y <code>!LocalFlip,x</code>: volteos del sprite.

'''Resultado'''

* Carry activado: el sprite tiene una pose disponible para dibujar; desactivado si todavía no tiene ninguna.
* Guarda la pose que se puede dibujar en <code>!LastPoseIndex,x</code> y la ubicación de sus gráficos en <code>!LastPoseHashIndex,x</code>, igual que <code>!Upload</code>.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite003
!UploadWithoutPoseOffset
RTS
</pre>

<code>!DynamicPoseIDMySprite003</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre usa PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

=== DXDraw ===

<code>!DXDraw</code> dibuja una pose utilizando los gráficos dinámicos disponibles para el sprite.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalDraw()</code>.
* Cluster sprite: <code>%DXClusterDraw()</code>.
* Extended sprite: <code>%DXExtendedDraw()</code>.

'''Entradas'''

* A de 16 bits: ID de la pose de dibujo.
* X: índice del sprite.
* <code>!PropParam</code> (<code>$52</code>): propiedades adicionales, con formato <code>YXCC----</code>.
* <code>!MaxTilePriorityParam</code> (<code>$0A</code>): prioridad máxima de los tiles; <code>$00</code> máxima, <code>$01</code> alta, <code>$02</code> propia del tipo de sprite y <code>$03</code> mínima.
* <code>!Palette,x</code>, <code>!LastFlip,x</code> y <code>!LastPoseHashIndex,x</code>: paleta, volteo y ubicación de los gráficos disponibles.

'''Resultado'''

Dibuja la pose en pantalla. Si <code>!LastPoseHashIndex,x</code> contiene <code>$FF</code>, no dibuja. A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
Draw:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDraw
RTS
</pre>

En este ejemplo, las poses deben estar en el mismo orden en el DrawInfo y el DynamicInfo. Se utiliza <code>!LastPoseIndex</code> porque indica qué pose se puede dibujar: si la nueva todavía no se pudo cargar, seguirá mostrando la anterior.

<code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>. Los nombres de recurso y pose se normalizan en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>. Este ID de dibujo es distinto de los IDs <code>!DynamicPoseID...</code> del DynamicInfo.

=== DXDrawWithOffset ===

<code>!DXDrawWithOffset</code> permite dibujar la pose unos píxeles a la derecha, izquierda, arriba o abajo de la posición del sprite. Solo mueve el dibujo; el sprite sigue moviéndose y chocando en su posición original.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalDrawWithOffset()</code>.
* Cluster sprite: <code>%DXClusterDrawWithOffset()</code>.
* Extended sprite: <code>%DXExtendedDrawWithOffset()</code>.

'''Entradas'''

* Las mismas entradas de <code>!DXDraw</code>.
* <code>!XOffsetParam</code> (<code>$8A</code>): desplazamiento horizontal de 8 bits con signo.
* <code>!YOffsetParam</code> (<code>$8B</code>): desplazamiento vertical de 8 bits con signo.

'''Resultado'''

Dibuja igual que <code>!DXDraw</code>, pero suma los desplazamientos que preparaste. Un valor positivo en <code>!XOffsetParam</code> mueve el dibujo a la derecha; en <code>!YOffsetParam</code>, hacia abajo. Los valores negativos lo mueven a la izquierda o hacia arriba.

'''Ejemplo'''

<pre>
Draw:
LDA #$08
STA !XOffsetParam
LDA #$F8
STA !YOffsetParam
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDrawWithOffset
RTS
</pre>

El ejemplo desplaza el dibujo 8 píxeles a la derecha y 8 hacia arriba. <code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>; el nombre se normaliza en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>.

=== ReplacePalette ===

<code>!ReplacePalette</code> cambia los colores de la paleta que el sprite ya tiene asignada, sin cambiar su ID de asignación. Por ejemplo, permite sustituir su paleta normal por otra durante un estado especial. Como varios sprites pueden compartir esa paleta, todos ellos verán el cambio. Llámala cuando necesites cambiar los colores; repetirla cada frame obliga al sistema a volver a preparar la paleta y sus efectos.

Suele utilizarse después de <code>!PaletteAssignmentNoUpload</code>: primero se asigna la paleta sin cargar sus colores y después se reemplazan por los que quieres mostrar. Antes de llamar a <code>!ReplacePalette</code>, coloca en <code>$02-$04</code> la dirección de los nuevos colores.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalReplacePalette()</code>.
* Cluster sprite: <code>%DXClusterReplacePalette()</code>.
* Extended sprite: <code>%DXExtendedReplacePalette()</code>.

'''Entradas'''

* X: índice del sprite.
* A en modo de 8 bits.
* <code>$02-$04</code>: dirección ROM de la nueva paleta en BGR555.
* <code>!Palette,x</code>: paleta ya asignada.
* <code>!PaletteOption,x</code>: participación en el efecto global.

'''Resultado'''

* Carry activado: se puede dibujar con la paleta; si los nuevos colores todavía no están listos, se conservan los anteriores.
* Carry desactivado: la paleta todavía no tiene colores listos para dibujar.

Mantiene el mismo ID de paleta, pero solicita cambiar sus colores. Al marcar que el efecto debe volver a calcularse, utiliza <code>$FFFF</code> si nunca se habían obtenido colores para dibujar, o <code>$FFFE</code> si puede seguir mostrando los anteriores mientras prepara los nuevos.

'''Ejemplo'''

<pre>
ReplaceSpritePalette:
; Ejecutar cuando se necesite cambiar una paleta ya asignada.
LDA.b #!PaletteMyAlternatePalette
STA $02
LDA.b #!PaletteMyAlternatePalette>>8
STA $03
LDA.b #!PaletteMyAlternatePalette>>16
STA $04
!ReplacePalette
RTS
</pre>

<code>!PaletteMyAlternatePalette</code> es la dirección de una paleta insertada desde los recursos declarados en un DynamicInfo y se guarda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase: <code>my_alternate_palette</code> se convierte en <code>MyAlternatePalette</code>.

=== ConcatenateRGBPaletteEffectToGlobal ===

<code>!ConcatenateRGBPaletteEffectToGlobal</code> permite que la paleta del sprite tenga un efecto RGB propio y siga siendo afectada por el efecto global. Primero aplica el efecto local, como <code>PaletteTransitionRGB</code>, y después aplica el global sobre ese resultado. Llámala después de <code>!PaletteAssignmentNoUpload</code>, que deja preparada la paleta original.

El uso habitual es asignar primero la paleta con <code>!PaletteAssignmentNoUpload</code> y, si el carry está activado, llamar a esta rutina para aplicar los efectos y completar la carga de los colores.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalConcatenateRGBPaletteEffectToGlobal()</code>.
* Cluster sprite: <code>%DXClusterConcatenateRGBPaletteEffectToGlobal()</code>.
* Extended sprite: <code>%DXExtendedConcatenateRGBPaletteEffectToGlobal()</code>.

'''Entradas'''

* A de 16 bits: ID del efecto local RGB.
* X de 8 bits: copia aquí el valor de <code>!Palette,x</code> con <code>LDA !Palette,x</code> seguido de <code>TAX</code>, como en el ejemplo.
* Y de 8 bits: conserva el valor que dejó <code>!PaletteAssignmentNoUpload</code>. El valor 1 obliga a calcular de nuevo el efecto; 0 permite reutilizar el resultado anterior si no cambió nada.
* <code>$02-$04</code>: dirección de la paleta base BGR555 preparada por la asignación.
* <code>!PaletteOption</code>: el bit <code>E</code> debe estar activado para combinar con el efecto global.

'''Resultado'''

* Carry activado: se puede dibujar con la paleta. Si el nuevo efecto todavía no está listo, se sigue mostrando el anterior.
* Carry desactivado: todavía no hay colores listos para dibujar esa paleta.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

LDA !Palette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyRGBEffect0
!ConcatenateRGBPaletteEffectToGlobal
.Return
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y <code>!PaletteEffectIDMyRGBEffect0</code> desde un archivo <code>*.paleffect</code>. Ambos quedan en <code>DXDefines.asm</code>. Sus nombres se normalizan en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>. Si se necesita Y para seleccionar el efecto mediante una tabla, conserva su valor con <code>PHY</code> y restáuralo con <code>PLY</code> antes de concatenar.

=== ConcatenateHSLPaletteEffectToGlobal ===

<code>!ConcatenateHSLPaletteEffectToGlobal</code> permite que la paleta del sprite tenga un efecto HSL propio, como <code>MixH</code>, y siga siendo afectada por el efecto global. Primero aplica el efecto local y después el global. Llámala después de <code>!PaletteAssignmentNoUpload</code>, que deja preparada la paleta original.

El uso habitual es asignar primero la paleta con <code>!PaletteAssignmentNoUpload</code> y, si el carry está activado, llamar a esta rutina para aplicar los efectos y completar la carga de los colores.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalConcatenateHSLPaletteEffectToGlobal()</code>.
* Cluster sprite: <code>%DXClusterConcatenateHSLPaletteEffectToGlobal()</code>.
* Extended sprite: <code>%DXExtendedConcatenateHSLPaletteEffectToGlobal()</code>.

'''Entradas'''

* A de 16 bits: ID del efecto local HSL.
* X de 8 bits: copia aquí el valor de <code>!Palette,x</code> con <code>LDA !Palette,x</code> seguido de <code>TAX</code>, como en el ejemplo.
* Y de 8 bits: conserva el valor que dejó <code>!PaletteAssignmentNoUpload</code>. El valor 1 obliga a calcular de nuevo el efecto; 0 permite reutilizar el resultado anterior si no cambió nada.
* <code>$02-$04</code>: dirección de la paleta base BGR555 preparada por la asignación.
* <code>!PaletteOption</code>: el bit <code>E</code> debe estar activado para combinar con el efecto global.

'''Resultado'''

* Carry activado: se puede dibujar con la paleta. Si el nuevo efecto todavía no está listo, se sigue mostrando el anterior.
* Carry desactivado: todavía no hay colores listos para dibujar esa paleta.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

LDA !Palette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyHSLEffect0
!ConcatenateHSLPaletteEffectToGlobal
.Return
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y <code>!PaletteEffectIDMyHSLEffect0</code> desde un archivo <code>*.paleffect</code>. Quedan en <code>DXDefines.asm</code> y utilizan nombres normalizados en PascalCase: se eliminan separadores y se escribe en mayúscula la inicial de cada palabra. Conserva Y con <code>PHY</code>/<code>PLY</code> si lo utilizas temporalmente para seleccionar el efecto.

Ambas variantes de concatenación realizan las conversiones necesarias si el efecto local y el global utilizan espacios de color diferentes. Consulta [[es/Dynamic_Xtreme_files_and_formats#Tipos_de_efectos|Tipos de efectos]] para identificar los efectos RGB y HSL.

== Rutinas y Macros Generales ==

Estas rutinas y macros permiten trabajar con los sistemas de Dynamic Xtreme desde sprites, UberASM y otros códigos. En las macros puedes indicar qué variables y valores utilizar. Si un argumento contiene una coma, como <code>!NormalPoseIndex,x</code>, escríbelo entre comillas para que Asar lo lea como un solo argumento. Utiliza <code>#</code> al entregar un valor inmediato, como <code>#$04</code>.

Aplica también las reglas de [[#Estado del CPU y memoria temporal|DBR, direct page, flags y pila]]. Los contratos de cada familia indican qué registros y temporales debes guardar si necesitas conservarlos.

=== Consulta rápida de llamadas y retornos ===

Algunas macros ya incluyen el retorno que termina la rutina donde las escribes. En esos casos, el código colocado después de la macro no se ejecuta como continuación de esa rutina.

{| class="wikitable"
! Llamada o familia !! Retorno incluido !! Cómo utilizarla
|-
| Aliases para sprites: <code>!RenderBox</code>, <code>!Upload</code>, <code>!DXDraw</code>, <code>!PaletteAssignment</code> y los demás aliases de esta categoría.
| La llamada vuelve y el código continúa después del alias.
| Escribe el alias directamente, sin anteponer <code>JSR</code> ni <code>JSL</code>. Tu rutina conserva su propio retorno.
|-
| [[#GeneralUpload|GeneralUpload]], [[#Upload (macro general)|Upload (macro general)]] y [[#StandardSpriteUpload|StandardSpriteUpload]].
| <code>RTS</code>.
| Coloca la macro al final de una rutina llamada con <code>JSR</code>.
|-
| [[#Draw|Draw]], [[#StandardSpriteDraw|StandardSpriteDraw]] y [[#DrawStatic|DrawStatic]].
| <code>RTS</code>.
| Coloca la macro al final de una rutina llamada con <code>JSR</code>.
|-
| [[#PaletteAssignment (macro general)|PaletteAssignment]], [[#PaletteAssignmentNoUpload (macro general)|PaletteAssignmentNoUpload]], [[#StandardSpritePaletteAssignment|StandardSpritePaletteAssignment]] y [[#StandardSpritePaletteAssignmentNoUpload|StandardSpritePaletteAssignmentNoUpload]].
| <code>RTL</code>.
| Coloca la macro al final de una rutina llamada con <code>JSL</code>.
|-
| [[#ReplacePalette (macro general)|ReplacePalette]], [[#Combinar un efecto propio con el global|ConcatenateRGBPaletteEffectToGlobal y ConcatenateHSLPaletteEffectToGlobal]], en sus versiones de macro general.
| <code>RTL</code>.
| Coloca la macro al final de una rutina llamada con <code>JSL</code>.
|-
| [[#LoadPaletteIDAndAddress|LoadPaletteIDAndAddress]] y [[#DefineDynamicSpaceConfig|DefineDynamicSpaceConfig]].
| Ninguno: continúa el código siguiente.
| Puedes escribir más código después de la macro. Tu rutina debe incluir su propio retorno.
|-
| [[#Cargar colores con TransferPalette|TransferPaletteFromAddress, FromPointer, FromTable, Resource y ResourceWithLength]].
| Ninguno: continúa el código siguiente.
| Comprueba el carry después de la macro y continúa o termina tu rutina según el resultado.
|-
| Macros de [[#Efectos de paleta|preparación de bases, mezcla, transición, DoEffect y conversión]], incluidas sus variantes <code>Default</code>.
| Ninguno: continúa el código siguiente.
| Puedes encadenar operaciones después de la macro. Las dos macros de concatenación son la excepción indicada arriba.
|-
| Macros de [[#PPU|transferencia a VRAM y CGRAM]], incluidas las variantes <code>Forced</code>, y macros de [[#Matemáticas|matemáticas]].
| Ninguno: continúa el código siguiente.
| Tu rutina debe incluir su propio retorno.
|-
| Rutinas del parche [[#DynamicPoseSpaceConfig|DynamicPoseSpaceConfig]], [[#TakeDynamicRequest|TakeDynamicRequest]] y [[#DynamicRoutine|DynamicRoutine]].
| La rutina llamada retorna con <code>RTL</code>.
| Utiliza <code>JSL !NombreDeLaRutina</code>. Al volver, se ejecuta la instrucción que sigue al <code>JSL</code>; tu rutina conserva su propio retorno.
|}

Por ejemplo, una rutina que contiene <code>%Upload(...)</code> se llama con <code>JSR PoseManagement</code> y ya termina con el <code>RTS</code> de la macro. Una que contiene <code>%PaletteAssignment(...)</code> se llama con <code>JSL PaletteManagement</code> y ya termina con su <code>RTL</code>. En cambio, <code>!Upload</code> realiza una llamada a la rutina compartida de PIXI y permite continuar después del alias: no es lo mismo que expandir <code>%Upload(...)</code> directamente.

=== Poses dinámicas ===

==== DynamicPoseSpaceConfig ====

'''Registros y memoria temporal:''' entra con A, X e Y en 8 bits. Modifica A y X; conserva Y y los tamaños de los registros. No utiliza scratch. Guarda y restaura DBR alrededor de la selección de configuración. No devuelve un resultado en carry. Se llama con <code>JSL</code> y retorna con <code>RTL</code>.

<code>JSL !DynamicPoseSpaceConfig</code> elige qué partes de la memoria gráfica (VRAM) puede usar Dynamic Xtreme para cargar poses dinámicas. Normalmente se llama desde el <code>init</code> de UberASM al entrar al nivel.

Los defines con las configuraciones disponibles se encuentran en <code>DXDefines.asm</code>, bajo los nombres <code>!DynamicSpaceConfig...</code>.

'''Entrada'''

* A de 8 bits: una de las configuraciones <code>!DynamicSpaceConfig...</code> de <code>DXDefines.asm</code>. Sus valores van de <code>$00</code> a <code>$1C</code>.

'''Resultado'''

Después de la llamada, Dynamic Xtreme solo puede elegir espacio dentro de las regiones seleccionadas para cargar poses nuevas. Las poses que ya estaban en VRAM no se eliminan al cambiar esta opción. Lo habitual es configurarla al entrar al nivel, antes de que los sprites soliciten sus gráficos.

'''Ejemplo'''

<pre>
init:
LDA #!DynamicSpaceConfigSP4
JSL !DynamicPoseSpaceConfig
RTL
</pre>

<code>!DynamicSpaceConfigSP4</code> es una constante publicada en <code>DXDefines.asm</code> que permite utilizar SP4. Otras opciones incluyen <code>!DynamicSpaceConfigSP3</code>, <code>!DynamicSpaceConfigSP34</code> y <code>!DynamicSpaceConfigSP234</code>. Selecciona una región que no se superponga con los gráficos estáticos utilizados por el nivel.

==== DefineDynamicSpaceConfig ====

<code>%DefineDynamicSpaceConfig()</code> permite definir qué espacios de la VRAM pueden utilizarse para poses dinámicas y cuáles quedan restringidos. Se utiliza para crear una configuración propia, en lugar de elegir una de las configuraciones predefinidas de <code>!DynamicPoseSpaceConfig</code>.

'''Parámetros'''

<pre>
%DefineDynamicSpaceConfig(init, end, restricted)
</pre>

* <code>init</code>: ID del primer bloque de 16×16 del espacio.
* <code>end</code>: ID del último bloque de 16×16 del espacio. Ambos extremos se incluyen.
* <code>restricted</code>: <code>$00</code> permite utilizar ese espacio para poses dinámicas; <code>$80</code> lo restringe y el sistema no puede elegirlo para cargar poses.

Los tres parámetros son constantes utilizadas al ensamblar y se escriben sin <code>#</code>. El primer bloque debe ser menor o igual que el último, y ambos deben estar entre <code>$00</code> y <code>$7F</code>. Por ejemplo, <code>$60</code> hasta <code>$7F</code> incluye 32 bloques.

'''Cómo se numeran los bloques'''

Para esta configuración, el espacio de gráficos de sprites se considera una cuadrícula de '''128×256 píxeles'''. La mitad superior, de 128×128, corresponde a SP1 y SP2; la mitad inferior, también de 128×128, corresponde a SP3 y SP4.

La cuadrícula se divide en bloques de 16×16: hay '''8 bloques por fila y 16 filas''', para un total de 128 bloques. Sus IDs se numeran de izquierda a derecha y después se continúa en la fila siguiente, de arriba abajo:

{| class="wikitable"
! Fila de tiles de 16×16 !! Col. 0 !! Col. 1 !! Col. 2 !! Col. 3 !! Col. 4 !! Col. 5 !! Col. 6 !! Col. 7
|-
! 0
| <code>$00</code> || <code>$01</code> || <code>$02</code> || <code>$03</code> || <code>$04</code> || <code>$05</code> || <code>$06</code> || <code>$07</code>
|-
! 1
| <code>$08</code> || <code>$09</code> || <code>$0A</code> || <code>$0B</code> || <code>$0C</code> || <code>$0D</code> || <code>$0E</code> || <code>$0F</code>
|-
! 2
| <code>$10</code> || <code>$11</code> || <code>$12</code> || <code>$13</code> || <code>$14</code> || <code>$15</code> || <code>$16</code> || <code>$17</code>
|-
! 3
| <code>$18</code> || <code>$19</code> || <code>$1A</code> || <code>$1B</code> || <code>$1C</code> || <code>$1D</code> || <code>$1E</code> || <code>$1F</code>
|-
! 4
| <code>$20</code> || <code>$21</code> || <code>$22</code> || <code>$23</code> || <code>$24</code> || <code>$25</code> || <code>$26</code> || <code>$27</code>
|-
! 5
| <code>$28</code> || <code>$29</code> || <code>$2A</code> || <code>$2B</code> || <code>$2C</code> || <code>$2D</code> || <code>$2E</code> || <code>$2F</code>
|-
! 6
| <code>$30</code> || <code>$31</code> || <code>$32</code> || <code>$33</code> || <code>$34</code> || <code>$35</code> || <code>$36</code> || <code>$37</code>
|-
! 7
| <code>$38</code> || <code>$39</code> || <code>$3A</code> || <code>$3B</code> || <code>$3C</code> || <code>$3D</code> || <code>$3E</code> || <code>$3F</code>
|-
! 8
| <code>$40</code> || <code>$41</code> || <code>$42</code> || <code>$43</code> || <code>$44</code> || <code>$45</code> || <code>$46</code> || <code>$47</code>
|-
! 9
| <code>$48</code> || <code>$49</code> || <code>$4A</code> || <code>$4B</code> || <code>$4C</code> || <code>$4D</code> || <code>$4E</code> || <code>$4F</code>
|-
! 10
| <code>$50</code> || <code>$51</code> || <code>$52</code> || <code>$53</code> || <code>$54</code> || <code>$55</code> || <code>$56</code> || <code>$57</code>
|-
! 11
| <code>$58</code> || <code>$59</code> || <code>$5A</code> || <code>$5B</code> || <code>$5C</code> || <code>$5D</code> || <code>$5E</code> || <code>$5F</code>
|-
! 12
| <code>$60</code> || <code>$61</code> || <code>$62</code> || <code>$63</code> || <code>$64</code> || <code>$65</code> || <code>$66</code> || <code>$67</code>
|-
! 13
| <code>$68</code> || <code>$69</code> || <code>$6A</code> || <code>$6B</code> || <code>$6C</code> || <code>$6D</code> || <code>$6E</code> || <code>$6F</code>
|-
! 14
| <code>$70</code> || <code>$71</code> || <code>$72</code> || <code>$73</code> || <code>$74</code> || <code>$75</code> || <code>$76</code> || <code>$77</code>
|-
! 15
| <code>$78</code> || <code>$79</code> || <code>$7A</code> || <code>$7B</code> || <code>$7C</code> || <code>$7D</code> || <code>$7E</code> || <code>$7F</code>
|}

Cada celda representa un tile de 16×16 y contiene su ID de bloque. Las filas se numeran del 0 al 15 y las columnas del 0 al 7. Estos IDs no son los TileCodes de 8×8 que utiliza el DrawInfo.

{| class="wikitable"
! Sección !! Bloques !! Posición en la cuadrícula
|-
| SP1 || <code>$00–$1F</code> || Primeras cuatro filas.
|-
| SP2 || <code>$20–$3F</code> || Siguientes cuatro filas.
|-
| SP3 || <code>$40–$5F</code> || Siguientes cuatro filas.
|-
| SP4 || <code>$60–$7F</code> || Últimas cuatro filas.
|}

'''Ejemplos del parche'''

Estas configuraciones utilizan los mismos rangos que las opciones predefinidas del parche. Colócalas en el <code>init</code> de UberASM, antes de que los sprites soliciten sus poses.

'''Utilizar solamente SP4:'''

<pre>
init:
; SP1, SP2 y SP3 restringidos.
%DefineDynamicSpaceConfig($00, $5F, $80)

; SP4 disponible para poses dinámicas.
%DefineDynamicSpaceConfig($60, $7F, $00)
RTL
</pre>

'''Utilizar solamente SP3:'''

<pre>
init:
; SP1 y SP2 restringidos.
%DefineDynamicSpaceConfig($00, $3F, $80)

; SP3 disponible para poses dinámicas.
%DefineDynamicSpaceConfig($40, $5F, $00)

; SP4 restringido.
%DefineDynamicSpaceConfig($60, $7F, $80)
RTL
</pre>

'''Utilizar SP3 y SP4:'''

<pre>
init:
; SP1 y SP2 restringidos.
%DefineDynamicSpaceConfig($00, $3F, $80)

; SP3 y SP4 disponibles como un solo espacio.
%DefineDynamicSpaceConfig($40, $7F, $00)
RTL
</pre>

Cada ejemplo es una alternativa: utiliza una configuración completa, cubriendo los bloques <code>$00–$7F</code> con espacios consecutivos y sin superponerlos. Restringe los bloques que utilicen el jugador, sprites estáticos u otros recursos cuyos gráficos deban mantenerse. La macro no detecta esos usos por ti.

'''Registros y resultado'''

* A debe estar en modo de 8 bits. La macro modifica A y los flags N/Z; conserva X, Y, carry, DBR y D, y no cambia el tamaño de los registros.
* Escribe la configuración en <code>DX_Dynamic_Tile_Size</code> y <code>DX_Dynamic_Tile_Offset</code>, en los extremos del espacio indicado. No utiliza scratch.
* No carga gráficos ni mueve poses que ya estén en VRAM. Utilízala para preparar el espacio al entrar al nivel.
* No devuelve éxito o fallo en carry y no incluye <code>RTS</code> ni <code>RTL</code>: el código continúa después de cada llamada. El <code>RTL</code> de los ejemplos termina el <code>init</code> de UberASM.

==== TakeDynamicRequest ====

'''Registros y memoria temporal:''' entra con A de 8 bits y X/Y de 16 bits. Al volver, A, X e Y quedan en 8 bits; sus valores pueden cambiar. X solo es un índice de caché válido si el carry está activado; no conserva el índice del sprite. Puede sobrescribir <code>$00-$0F</code> y <code>$47-$51</code> al preparar una carga nueva. Conserva DBR y D, tanto en éxito como en fallo. Se llama con <code>JSL</code> y retorna con <code>RTL</code>.

<code>JSL !TakeDynamicRequest</code> recibe el número que identifica una pose y busca sus gráficos en VRAM. Si ya están cargados, marca que siguen en uso para evitar que sean sobrescritos. Si no están, busca espacio y deja preparada su carga para el próximo NMI, el momento entre imágenes en que el juego actualiza los gráficos.

'''Entrada'''

* Y de 16 bits: ID exacto de la pose dinámica.

'''Resultado'''

* Carry activado: los gráficos ya están en VRAM o se programó su carga para el próximo NMI. X contiene el índice de la entrada de caché que guarda su ubicación.
* Carry desactivado: no hay espacio suficiente en VRAM o cargar la pose superaría el límite de bytes que se pueden transferir durante ese frame.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
RequestPose:
REP #$10
LDY #!DynamicPoseIDMySprite000
JSL !TakeDynamicRequest
BCC .Unavailable

; X contiene el índice hash de la pose solicitada.
; Aquí tu código puede guardar ese índice para dibujar la pose.
RTS
.Unavailable
; Aquí se maneja la falta de recursos.
RTS
</pre>

<code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y se guarda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores y escribiendo en mayúscula la inicial de cada palabra: <code>my_sprite</code> pasa a <code>MySprite</code>.

Esta llamada devuelve dónde quedaron registrados los gráficos, pero no lo guarda en las variables del sprite ni elige la pose anterior si la solicitud falla. Para ese manejo completo utiliza <code>!Upload</code>.

==== DynamicRoutine ====

'''Registros y memoria temporal:''' establece A, X e Y en 16 bits para sus cálculos y los deja en 8 bits al volver. Los tres registros pueden cambiar. Puede sobrescribir <code>$00-$0B</code> y <code>$47-$51</code>; <code>PoseIDBackup</code> corresponde a los dos bytes de <code>$02-$03</code> de la direct page. Conserva D y no cambia DBR: debes preparar el banco de las tablas antes de llamarla. Se llama con <code>JSL</code> y retorna con <code>RTL</code>.

<code>JSL !DynamicRoutine</code> añade a la cola de transferencias la carga de los gráficos de una pose en una posición concreta de VRAM. La copia se realiza durante NMI.

La rutina necesita saber dos cosas: qué pose copiar y dónde colocarla. Recibe el destino en A, pero obtiene el ID de la pose desde una variable interna llamada <code>PoseIDBackup</code>. <code>!TakeDynamicRequest</code> prepara esos datos antes de llamarla.

'''Datos que necesita la llamada'''

* A, en sus 8 bits bajos: posición donde comenzarán los gráficos dentro del mapa de bloques utilizado por el sistema dinámico. La rutina convierte este valor a una dirección de VRAM.
* <code>PoseIDBackup</code>: variable interna de 16 bits que contiene el ID de la pose que se va a copiar.
* DBR (registro que selecciona el banco de datos): debe tener el banco donde están las tablas de direcciones y tamaños de las poses.

Antes de llamarla, el código debe haber reservado suficiente espacio en VRAM y comprobado que la carga cabe en el límite de bytes del frame. <code>!TakeDynamicRequest</code> realiza ambas tareas.

'''Resultado'''

Lee la dirección y el tamaño de los gráficos de la pose, calcula cómo distribuirlos en el destino y agrega las copias necesarias a la cola de VRAM. A, X e Y quedan en modo de 8 bits. El carry no indica si la operación tuvo éxito.

'''Ejemplo de funcionamiento'''

Cuando un sprite solicita una pose que todavía no está en VRAM, <code>!TakeDynamicRequest</code> busca dónde colocarla. Después guarda su ID en <code>PoseIDBackup</code> y llama a <code>!DynamicRoutine</code> con la posición elegida en A. Esta última prepara la copia de los gráficos; el NMI ejecuta la transferencia.

Para cargar una pose desde el código de un sprite, utiliza <code>!Upload</code>. Si necesitas hacer la solicitud directamente mediante su ID, utiliza <code>!TakeDynamicRequest</code>. Llamar a <code>!DynamicRoutine</code> requiere preparar también la variable interna del ID, el banco de datos y el espacio de destino descritos arriba.

==== GeneralUpload ====

'''Registros y memoria temporal:''' entra con A de 16 bits y X/Y de 8 bits. Al terminar, A, X e Y quedan en 8 bits. A e Y pueden cambiar; con <code>sprite = 1</code> o <code>2</code>, X se recupera desde <code>!SpriteIndex</code>; con <code>sprite = 0</code>, no se conserva X. Puede sobrescribir <code>$00-$0F</code> y <code>$47-$51</code>, incluidos los temporales de una solicitud nueva. Conserva DBR y D. Incluye <code>RTS</code>: llama con <code>JSR</code> a la rutina que contiene la macro.

<code>%GeneralUpload()</code> realiza el mismo trabajo de carga que las rutinas para sprites, pero te permite elegir las variables donde guardar el índice de pose, el volteo y la ubicación de sus gráficos. Sirve, por ejemplo, para una entidad que necesita manejar varias poses independientes o para un código que utiliza sus propias tablas.

'''Parámetros'''

<pre>
%GeneralUpload(Pose16, checkLast, sprite, flip, safeCheck, withoutOffset,
safeLow, safeHigh, poseIndex, lastPoseIndex, lastPoseHashIndex,
globalFlip, localFlip, lastFlip)
</pre>

La firma anterior muestra el orden de los parámetros; escribe la llamada en una sola línea.

* <code>Pose16</code>: 0 utiliza índices de pose de 8 bits; 1 utiliza índices de 16 bits.
* <code>checkLast</code>: 1 permite seguir dibujando la pose anterior si no se pudo obtener la nueva; 0 desactiva esa opción.
* <code>sprite</code>: 0 para usar variables propias sin recuperar el índice del sprite; 1 para trabajar con las tablas del sprite, recuperando X desde <code>!SpriteIndex</code>; 2 funciona como 1, pero solicita la pose sin comparar ni cambiar <code>lastPoseIndex</code>.
* <code>flip</code>: 1 combina <code>globalFlip</code> y <code>localFlip</code> en <code>lastFlip</code>; 0 omite esa actualización.
* <code>safeCheck</code>: 1 evita repetir la solicitud en el mismo frame utilizando <code>safeLow</code> y <code>safeHigh</code>; 0 omite la comprobación.
* <code>withoutOffset</code>: 0 suma <code>poseIndex</code> al ID base; 1 utiliza directamente el ID recibido.
* <code>safeLow</code> y <code>safeHigh</code>: variables que guardan los bytes bajo y alto del frame de la solicitud. Se escriben incluso cuando <code>safeCheck</code> es 0.
* <code>poseIndex</code>: variable del índice de pose deseado.
* <code>lastPoseIndex</code>: variable del último índice de pose disponible.
* <code>lastPoseHashIndex</code>: variable que identifica la entrada donde Dynamic Xtreme guarda la ubicación de los gráficos en VRAM. <code>$FF</code> indica que todavía no hay gráficos disponibles.
* <code>globalFlip</code>, <code>localFlip</code> y <code>lastFlip</code>: variables del volteo global, local y efectivo.

'''Entrada adicional'''

* A de 16 bits: ID dinámico base o exacto, según <code>withoutOffset</code>.
* Para <code>sprite = 1</code> o <code>sprite = 2</code>, <code>!SpriteIndex</code> debe contener el índice del sprite.

Con <code>sprite = 2</code>, la macro solicita la pose aunque <code>poseIndex</code> y <code>lastPoseIndex</code> sean iguales, y deja <code>lastPoseIndex</code> sin modificar. Si consigue los gráficos, guarda su ubicación en <code>lastPoseHashIndex</code>. Si la solicitud falla y <code>checkLast</code> es 1, puede seguir usando los gráficos anteriores. <code>safeCheck</code> sigue controlando si se permite repetir la solicitud durante el mismo frame.

Este valor 2 no cambia el tamaño de los índices. Para utilizar variables de índice de 16 bits se selecciona <code>Pose16 = 1</code>. El ID dinámico entregado en A siempre es de 16 bits.

<code>sprite = 2</code> suele utilizarse en sprites dinámicos formados por varias piezas, como una cabeza y un cuerpo que necesitan cambiar sus gráficos al mismo tiempo. Al dejar <code>lastPoseIndex</code> sin modificar, permite que el código del sprite coordine el cambio de todas las piezas antes de actualizar el índice de pose. La macro no sincroniza las piezas por sí sola: esa coordinación la realiza el código que la llama.

'''Resultado'''

Devuelve el carry activado cuando hay una pose disponible para dibujar: la solicitada o la anterior si <code>checkLast</code> permite conservarla. Si no hay ninguna, devuelve el carry desactivado. Guarda la información de esa pose en las variables indicadas y marca sus gráficos como usados para evitar que sean sobrescritos. La macro incluye un <code>RTS</code> al final; colócala al final de una rutina llamada con <code>JSR</code>.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%GeneralUpload(0, 1, 1, 1, 1, 0, "!NormalSafeFrameLowByte,x", "!NormalSafeFrameHighByte,x", "!NormalPoseIndex,x", "!NormalLastPoseIndex,x", "!NormalLastPoseHashIndex,x", "!NormalGlobalFlip,x", "!NormalLocalFlip,x", "!NormalLastFlip,x")
</pre>

El ejemplo utiliza las tablas de un sprite normal y un índice de pose de 8 bits. <code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>; el nombre se normaliza en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>.

==== Upload (macro general) ====

'''Registros y memoria temporal:''' utiliza el mismo contrato de [[#GeneralUpload|GeneralUpload]], con <code>Pose16 = 0</code>. A entra en 16 bits, X/Y en 8 bits, y los tres quedan en 8 bits. El valor de <code>sprite</code> determina si X vuelve a cargarse desde <code>!SpriteIndex</code>. La macro incluye <code>RTS</code>.

<code>%Upload()</code> es la variante de <code>%GeneralUpload()</code> para índices de pose de 8 bits. No debe confundirse con el alias para sprites <code>!Upload</code>.

'''Parámetros'''

<pre>
%Upload(sprite, checkLast, flip, safeCheck, withoutOffset,
safeLow, safeHigh, poseIndex, lastPoseIndex, lastPoseHashIndex,
globalFlip, localFlip, lastFlip)
</pre>

Recibe los mismos datos que <code>%GeneralUpload()</code>, pero los índices guardados en las variables siempre son de 8 bits. La macro ya incluye el <code>RTS</code> que termina la rutina.

El parámetro <code>sprite</code> también admite 2: omite la comparación con <code>lastPoseIndex</code> y no actualiza esa variable, pero sí actualiza <code>lastPoseHashIndex</code> al obtener la pose. No habilita índices de 16 bits; para eso se utiliza <code>%GeneralUpload()</code> con <code>Pose16 = 1</code>.

Este modo suele usarse para coordinar sprites dinámicos con varias piezas y hacer que cambien sus gráficos al mismo tiempo. Por ejemplo, el código puede manejar por separado la carga de la cabeza y del cuerpo, y actualizar el índice de pose cuando corresponda cambiar ambas partes juntas. Como la macro deja <code>lastPoseIndex</code> sin modificar, el código del sprite puede controlar ese cambio.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%Upload(1, 1, 1, 1, 0, "!NormalSafeFrameLowByte,x", "!NormalSafeFrameHighByte,x", "!NormalPoseIndex,x", "!NormalLastPoseIndex,x", "!NormalLastPoseHashIndex,x", "!NormalGlobalFlip,x", "!NormalLocalFlip,x", "!NormalLastFlip,x")
</pre>

<code>!DynamicPoseIDMySprite000</code> es generado desde el DynamicInfo y se guarda en <code>DXDefines.asm</code>. El nombre usa PascalCase eliminando separadores: <code>my_sprite</code> pasa a <code>MySprite</code>.

==== StandardSpriteUpload ====

'''Registros y memoria temporal:''' utiliza el contrato de [[#GeneralUpload|GeneralUpload]] con <code>sprite = 1</code>. A entra en 16 bits y X/Y en 8 bits. Al volver, X contiene <code>!SpriteIndex</code>; A e Y pueden cambiar y los tres quedan en 8 bits. Comparte sus scratch y termina con <code>RTS</code>.

<code>%StandardSpriteUpload(withoutOffset, type)</code> selecciona automáticamente las tablas de Dynamic Xtreme correspondientes a un sprite normal, cluster o extended. Es la macro utilizada por las rutinas PIXI de carga.

'''Parámetros y entradas'''

* <code>withoutOffset</code>: 0 suma <code>!PoseIndex</code> al ID base; 1 utiliza el ID exacto.
* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code> o <code>"Extended"</code>.
* A de 16 bits: ID dinámico.
* <code>!SpriteIndex</code>: índice del sprite.
* Tablas de poses y volteo de Dynamic Xtreme del tipo seleccionado, inicializadas como en las rutinas <code>!Upload</code>.

'''Resultado'''

Selecciona las variables del tipo de sprite indicado. Permite conservar la pose anterior si la nueva no está lista, actualiza el volteo y evita repetir la solicitud durante el mismo frame. El carry funciona igual que en <code>!Upload</code>. La macro ya incluye el <code>RTS</code> que termina la rutina.

'''Ejemplo'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%StandardSpriteUpload(0, "Normal")
</pre>

<code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase: <code>my_sprite</code> pasa a <code>MySprite</code>, eliminando los separadores.

=== Dibujo de poses ===

Las macros de esta categoría terminan la rutina que las contiene mediante <code>RTS</code>. Los ejemplos deben llamarse con <code>JSR</code>. A debe contener el ID de dibujo con 16 bits; <code>!PropParam</code> (<code>$52</code>) y <code>!MaxTilePriorityParam</code> (<code>$0A</code>) se preparan igual que para <code>!DXDraw</code>.

==== Draw ====

'''Registros y memoria temporal:''' entra con A de 16 bits y X/Y de 8 bits. A e Y pueden cambiar. Con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code> al preparar un dibujo válido; con <code>sprite = 0</code>, no se conserva el X inicial. Si no hay pose válida, X no cambia. Los tres registros quedan en 8 bits. Puede sobrescribir <code>$00-$0F</code>, <code>$45-$4F</code> y <code>$8A</code>; con <code>offset = 1</code>, también <code>$8B-$8C</code>. Conserva DBR y D. Incluye <code>RTS</code>.

<code>%Draw()</code> dibuja una pose dinámica. En la llamada indicas qué gráficos usar, su paleta, su volteo y la posición donde quieres dibujarla.

'''Parámetros'''

<pre>
%Draw(offset, sprite, lastPoseHashIndex, lastFlip, palette, xl, xh, yl, yh)
</pre>

* <code>offset</code>: 0 utiliza las coordenadas entregadas; 1 añade <code>!XOffsetParam</code> (<code>$8A</code>) y <code>!YOffsetParam</code> (<code>$8B</code>), de 8 bits con signo.
* <code>sprite</code>: 1 recupera el índice del sprite en X desde <code>!SpriteIndex</code> antes de leer su paleta y posición; 0 omite ese paso.
* <code>lastPoseHashIndex</code>: variable que identifica dónde están registrados los gráficos de la pose en Dynamic Xtreme. Si contiene <code>$FF</code>, no se dibuja.
* <code>lastFlip</code>: variable o valor que indica el volteo con el que se dibujará.
* <code>palette</code>: variable o valor de la paleta; <code>$00</code> selecciona la 8, <code>$02</code> la 9, y así hasta <code>$0E</code> para la F.
* <code>xl</code> y <code>xh</code>: variables o valores de los bytes bajo y alto de la posición X.
* <code>yl</code> y <code>yh</code>: variables o valores de los bytes bajo y alto de la posición Y.

'''Resultado'''

Dibuja la pose con los gráficos indicados por <code>lastPoseHashIndex</code>, en la posición X e Y entregada. Puedes pasar las variables de posición de un sprite o indicar otra posición para dibujar desde UberASM u otro código.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
DrawPose:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMySprite_Frame0
%Draw(0, 1, "!NormalLastPoseHashIndex,x", "!NormalLastFlip,x", "!NormalPalette,x", "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

<code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y se guarda en <code>DXDefines.asm</code>. Los nombres se normalizan en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>. El ID debe corresponder a los gráficos dinámicos disponibles.

==== StandardSpriteDraw ====

'''Registros y memoria temporal:''' comparte el contrato y las scratch de [[#Draw|Draw]], con <code>sprite = 1</code>. Entra con A de 16 bits y X/Y de 8 bits. Prepara X con el índice del sprite antes de invocarla, porque lee su índice hash antes de recuperar <code>!SpriteIndex</code>. Al terminar deja los tres registros en 8 bits e incluye <code>RTS</code>.

<code>%StandardSpriteDraw(offset, type)</code> dibuja una pose dinámica utilizando las tablas de Dynamic Xtreme del tipo de sprite seleccionado.

'''Parámetros y entradas'''

* <code>offset</code>: 0 sin desplazamiento adicional; 1 utiliza los offsets de <code>$8A</code> y <code>$8B</code>.
* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code> o <code>"Extended"</code>.
* A de 16 bits: ID de dibujo.
* <code>!SpriteIndex</code>: índice del sprite.
* <code>!PropParam</code> y <code>!MaxTilePriorityParam</code>: propiedades y prioridad.
* Las tablas de paleta, último volteo e índice hash de Dynamic Xtreme del tipo seleccionado.

'''Resultado'''

El mismo que <code>%Draw()</code>, utilizando las tablas estándar. Es la macro que utilizan las rutinas PIXI <code>!DXDraw</code> y <code>!DXDrawWithOffset</code>.

Para sprites normales, las rutinas PIXI preparan los aliases de coordenadas <code>!NormalXLow</code>, <code>!NormalXHigh</code>, <code>!NormalYLow</code> y <code>!NormalYHigh</code>. Si se expande la macro directamente, también deben estar definidos, como en este ejemplo.

'''Ejemplo'''

<pre>
!NormalXLow = !SpriteXLow
!NormalXHigh = !SpriteXHigh
!NormalYLow = !SpriteYLow
!NormalYHigh = !SpriteYHigh

DrawPose:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMySprite_Frame0
%StandardSpriteDraw(0, "Normal")
</pre>

<code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>. Su nombre usa PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

==== DrawStatic ====

'''Registros y memoria temporal:''' entra con A de 16 bits y X/Y de 8 bits. A e Y pueden cambiar; X se conserva, pero los tres registros quedan en 8 bits. Puede sobrescribir <code>$00-$0F</code>, <code>$45-$4F</code> y <code>$8A</code>; con <code>offset = 1</code>, también <code>$8B-$8C</code>. El parámetro <code>sprite</code> no recupera X desde <code>!SpriteIndex</code> en esta macro. Conserva DBR y D. Incluye <code>RTS</code>.

<code>%DrawStatic()</code> dibuja una pose estática, declarada con <code>.IsStatic</code> en el DrawInfo. Sus gráficos deben estar previamente cargados en las posiciones de VRAM indicadas por sus tiles.

'''Parámetros'''

<pre>
%DrawStatic(offset, sprite, lastFlip, palette, xl, xh, yl, yh)
</pre>

* <code>offset</code>: 0 sin desplazamiento adicional; 1 utiliza <code>!XOffsetParam</code> (<code>$8A</code>) y <code>!YOffsetParam</code> (<code>$8B</code>), con signo.
* <code>sprite</code>: parámetro conservado en la firma; la implementación actual de esta macro no lo utiliza.
* <code>lastFlip</code>: variable o valor que indica el volteo; <code>#$00</code> dibuja sin volteo.
* <code>palette</code>: variable o valor de paleta: <code>#$00</code> selecciona la 8, <code>#$02</code> la 9, y así hasta <code>#$0E</code> para la F.
* <code>xl</code> y <code>xh</code>: variables o valores de los bytes bajo y alto de la posición X.
* <code>yl</code> y <code>yh</code>: variables o valores de los bytes bajo y alto de la posición Y.

'''Entradas adicionales'''

* A de 16 bits: ID de dibujo estático.
* <code>!PropParam</code> (<code>$52</code>) y <code>!MaxTilePriorityParam</code> (<code>$0A</code>): propiedades y prioridad.
* <code>!Tile</code> (<code>$05</code>): número de tile, cuando todos los tiles de la pose están definidos con el valor predeterminado 0. Si el DrawInfo declara otros valores, utiliza esos tiles directamente.

'''Resultado'''

Dibuja la pose sin consultar la caché de gráficos dinámicos. No requiere <code>!LastPoseHashIndex</code> ni una llamada previa a <code>!Upload</code>.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
DrawPose:
LDA #$80
STA !Tile
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMyStaticSprite_Frame0
%DrawStatic(0, 1, #$00, #$04, "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

El ejemplo utiliza el tile <code>$80</code> si la pose está configurada para tomarlo desde <code>!Tile</code>, sin volteo y con la paleta A. <code>!PoseIDMyStaticSprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>. Su nombre usa PascalCase eliminando separadores y poniendo en mayúscula la inicial de cada palabra: <code>my_static_sprite</code> pasa a <code>MyStaticSprite</code>.

=== Paletas ===

Estas macros permiten elegir qué paleta usa un sprite, cargar sus colores y cambiarlos durante el juego.

==== LoadPaletteIDAndAddress ====

'''Registros y memoria temporal:''' entra con A de 8 bits; la macro establece los tamaños que necesita para calcular las direcciones. Modifica A y X. Y no se utiliza, pero pasa a modo de 8 bits y pierde su byte alto si antes estaba en 16 bits. Al terminar los tres registros quedan en 8 bits. Escribe <code>$00-$04</code> y lee <code>$0E-$0F</code>. Conserva DBR y D; carry no es un indicador de éxito. La expansión continúa en la instrucción siguiente.

<code>%LoadPaletteIDAndAddress()</code> permite saber qué número identifica una paleta y dónde están guardados sus colores en la ROM. Elige una de las paletas del DynamicInfo: 0 para la primera, 1 para la segunda, etc. La llamada no carga colores en el juego; solo te entrega esos datos para usarlos después.

'''Entradas'''

* A de 8 bits: índice de la paleta dentro del DynamicInfo.
* <code>$0E-$0F</code>: guarda aquí el define <code>!MySpritePaletteTableOffset</code> de tu DynamicInfo, con 16 bits, como muestra el ejemplo.

'''Resultado'''

* <code>$00-$01</code>: ID de la paleta.
* <code>$02-$04</code>: dirección de sus colores en ROM, en formato BGR555.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
REP #$20
LDA #!MySpritePaletteTableOffset
STA $0E
SEP #$20

LDA #$01 ; Segunda paleta del DynamicInfo
%LoadPaletteIDAndAddress()
; $00-$01 contiene su ID y $02-$04 su dirección ROM.
</pre>

En PIXI también puede llamarse mediante <code>%DXLoadPaletteIDAndAddress()</code>, con las mismas entradas y resultados. Esta variante llama a una rutina compartida y después continúa con el código siguiente.

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza eliminando espacios, guiones bajos y guiones, y poniendo en mayúscula la inicial de cada palabra: <code>my_sprite</code> pasa a <code>MySprite</code>.

==== PaletteAssignment (macro general) ====

'''Registros y memoria temporal:''' entra con X/Y de 8 bits y A de 16 bits cuando <code>PalettesChange</code> está habilitado. Si está deshabilitado, entra con A de 8 bits y no se utiliza el offset de tabla. A e Y pueden cambiar; con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code> cuando se utiliza internamente; con <code>sprite = 0</code>, no se conserva X. Al volver, los tres quedan en 8 bits. Puede sobrescribir <code>$00-$0F</code>, <code>$D5</code> y los temporales de efectos cuando corresponda. Conserva DBR y D. La macro termina con <code>RTL</code>.

<code>%PaletteAssignment()</code> asigna y carga una paleta igual que <code>!PaletteAssignment</code>, pero permite indicar las variables donde se guardan sus opciones y su estado. Se puede usar para manejar una paleta adicional de un sprite o para un código con variables propias.

Si la paleta ya estaba asignada, mantiene su temporizador de uso en 2 para que no sea reemplazada mientras se utiliza. Si el bit <code>$80</code> de las opciones está activado, también aplica el efecto global correspondiente.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteAssignment(sprite, palette, paletteAssignment, paletteOption, paletteVersion, paletteLastVersion, manualIDGroup, manualID)
</pre>

* <code>sprite</code>: 1 utiliza <code>!SpriteIndex</code> para acceder a las tablas del sprite; 0 permite usar variables independientes del índice del sprite.
* <code>palette</code>: variable que recibe la paleta asignada. Debe comenzar en <code>$FF</code>. Los valores <code>$00</code>, <code>$02</code>, ..., <code>$0E</code> corresponden a las paletas 8-F.
* <code>paletteAssignment</code>: variable o valor con formato <code>--AA----</code>. <code>$00</code> permite que Dynamic Xtreme elija el destino y cargue los colores; <code>$10</code> utiliza el destino que tú indicas y carga los colores; <code>$20</code> utiliza ese destino con los colores que ya tiene el nivel.
* <code>paletteOption</code>: variable o valor con formato <code>EPPP----</code>. E = 1 permite aplicar el efecto global; E = 0 lo excluye. En modo manual, PPP elige entre la paleta 8 (<code>000</code>) y la F (<code>111</code>). En automático, <code>000</code> permite todas, <code>0XX</code> distinto de cero permite 8-B y <code>1XX</code> permite C-F. Los cuatro bits bajos no se usan para estas opciones.
* <code>paletteVersion</code>: variable o valor que selecciona una paleta de la lista del DynamicInfo: 0 para la primera, 1 para la segunda, etc. En las rutinas de sprites corresponde a <code>!Version,x</code>.
* <code>paletteLastVersion</code>: variable que guarda la última versión procesada. Debe comenzar en <code>$FF</code>.
* <code>manualIDGroup</code> y <code>manualID</code>: juntos forman el número con el que el sistema reconoce la paleta en los modos manuales. El primero indica el grupo: <code>#$FE</code> para normal, <code>#$FC</code> para cluster y <code>#$FD</code> para extended. El segundo indica el tipo de sprite; en uno normal se utiliza <code>!CustomSpriteNumber,x</code>, como en el ejemplo.

También puedes crear grupos propios: por ejemplo, usar <code>manualIDGroup = #$FB</code> para el jugador y <code>#$FA</code> para otro tipo de entidad. Son ejemplos, no valores predefinidos de Dynamic Xtreme. Elige valores que no estés utilizando para otro grupo y usa <code>manualID</code> para distinguir los recursos dentro de cada uno. Los grupos <code>$FE</code>, <code>$FD</code> y <code>$FC</code> ya son utilizados por las rutinas de sprites normales, extended y cluster, respectivamente.

'''Entrada adicional'''

* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> del DynamicInfo que contiene las paletas.
* Si <code>sprite = 1</code>, <code>!SpriteIndex</code> debe contener el índice del sprite.

'''Resultado'''

* Carry activado: hay una paleta con la que se puede dibujar; desactivado si todavía no hay ninguna.
* Guarda el número de paleta en <code>palette</code> y actualiza <code>paletteLastVersion</code> cuando procesa la versión.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
%PaletteAssignment(1, "!NormalPalette,x", "!NormalPaletteAssignment,x", "!NormalPaletteOption,x", "!NormalVersion,x", "!NormalLastVersion,x", #$FE, "!CustomSpriteNumber,x")
</pre>

El ejemplo utiliza las variables de un sprite normal. <code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

Llama a la rutina del ejemplo con <code>JSL PaletteManagement</code>. La macro ya incluye el <code>RTL</code> que termina la rutina, por lo que no debes añadir código después de ella.

==== PaletteAssignmentNoUpload (macro general) ====

'''Registros y memoria temporal:''' comparte el contrato de [[#PaletteAssignment (macro general)|PaletteAssignment (macro general)]]. Además de su carry, devuelve Y como se indica abajo; no conserves en Y otro dato que necesites después. Las salidas de <code>$00-$04</code> solo son válidas si se leyó una paleta del DynamicInfo. Termina con <code>RTL</code>.

<code>%PaletteAssignmentNoUpload()</code> elige una paleta como <code>%PaletteAssignment()</code>, pero deja pendiente la carga de sus colores. Permite aplicar después un efecto local y combinarlo con el global.

'''Parámetros y entradas'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteAssignmentNoUpload(sprite, palette, paletteAssignment, paletteOption, paletteVersion, paletteLastVersion, manualIDGroup, manualID)
</pre>

Los parámetros son los mismos que en <code>%PaletteAssignment()</code>. A recibe el offset de la tabla con 16 bits. <code>palette</code> y <code>paletteLastVersion</code> deben comenzar en <code>$FF</code>.

<code>paletteVersion</code> elige los colores de la lista del DynamicInfo: 0 para la primera paleta, 1 para la segunda, etc. <code>paletteAssignment</code> decide el modo: <code>$00</code> automático, <code>$10</code> manual y <code>$20</code> manual sin cargar colores. <code>paletteOption</code> utiliza <code>EPPP----</code>: E permite el efecto global y PPP selecciona la paleta 8-F en manual. En automático, <code>000</code> permite todas, <code>0XX</code> distinto de cero permite 8-B y <code>1XX</code> permite C-F. Para aplicar después un efecto local sobre los colores del DynamicInfo, utiliza el modo automático o manual con carga.

'''Resultado'''

* Carry activado: hay una paleta asignada; desactivado si no pudo obtenerse.
* <code>palette</code>: número de la paleta asignada, de dos en dos entre <code>$00</code> y <code>$0E</code>.
* <code>paletteLastVersion</code>: última versión procesada.
* <code>$00-$01</code>: ID de la paleta seleccionada del DynamicInfo.
* <code>$02-$04</code>: dirección ROM de sus colores.
* Y = 1 indica que se acaba de asignar la paleta y hay que calcular su efecto. Y = 0 indica que no hace falta recalcularlo por una asignación nueva.
* A, X e Y quedan en modo de 8 bits.

Usa los datos de <code>$00-$04</code> solo cuando la llamada leyó una paleta del DynamicInfo. Si usas una paleta del nivel sin cargarla, deshabilitaste los cambios de paleta o la llamada no se procesa en el modo de juego actual, esas direcciones pueden contener datos de otro código.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
AssignPaletteForEffect:
REP #$20
LDA #!MySpritePaletteTableOffset
%PaletteAssignmentNoUpload(1, "!NormalPalette,x", "!NormalPaletteAssignment,x", "!NormalPaletteOption,x", "!NormalVersion,x", "!NormalLastVersion,x", #$FE, "!CustomSpriteNumber,x")
</pre>

Después de llamar a <code>AssignPaletteForEffect</code> con <code>JSL</code>, comprueba el carry y aplica el efecto usando los datos devueltos. Conserva Y y <code>$02-$04</code> para la llamada de concatenación.

La macro ya termina la rutina con <code>RTL</code>. El código que aplica el efecto va después de la llamada <code>JSL AssignPaletteForEffect</code>, no después de la macro dentro de esa rutina.

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre usa PascalCase eliminando separadores: <code>my_sprite</code> pasa a <code>MySprite</code>.

==== StandardSpritePaletteAssignment ====

'''Registros y memoria temporal:''' comparte el contrato de [[#PaletteAssignment (macro general)|PaletteAssignment (macro general)]], con <code>sprite = 1</code>. Entra con X preparado para leer las tablas del sprite y con <code>!SpriteIndex</code> correspondiente al mismo sprite. Recupera X desde ese índice cuando lo utiliza internamente; A e Y pueden cambiar. Incluye <code>RTL</code>.

<code>%StandardSpritePaletteAssignment()</code> utiliza las variables de paleta del tipo de sprite indicado. Es la macro utilizada por las rutinas PIXI de asignación.

'''Parámetros y entradas'''

<pre>
%StandardSpritePaletteAssignment(type, manualIDGroup, manualID)
</pre>

* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code> o <code>"Extended"</code>.
* <code>manualIDGroup</code>: <code>#$FE</code> para normal, <code>#$FC</code> para cluster o <code>#$FD</code> para extended.
* También puedes elegir un grupo propio, por ejemplo <code>#$FB</code> para el jugador o <code>#$FA</code> para otro tipo de entidad, siempre que esos valores no estén siendo utilizados por otro grupo de tu proyecto.
* <code>manualID</code>: variable o valor que identifica el tipo de sprite en los modos manuales.
* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> del DynamicInfo que contiene las paletas.
* <code>!SpriteIndex</code>: índice del sprite.
* Las variables de Dynamic Xtreme para paleta, opciones, versión y última versión del tipo seleccionado, preparadas como en <code>!PaletteAssignment</code>.

'''Resultado'''

El mismo que <code>!PaletteAssignment</code>: guarda la paleta asignada en la tabla del sprite y devuelve el carry activado cuando se puede dibujar con ella.

La macro ya incluye un <code>RTL</code>. Llama a la rutina del ejemplo con <code>JSL PaletteManagement</code> y no añadas código después de la macro.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
%StandardSpritePaletteAssignment("Normal", #$FE, "!CustomSpriteNumber,x")
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase: <code>my_sprite</code> pasa a <code>MySprite</code> al eliminar los separadores.

==== StandardSpritePaletteAssignmentNoUpload ====

'''Registros y memoria temporal:''' comparte el contrato de [[#PaletteAssignmentNoUpload (macro general)|PaletteAssignmentNoUpload (macro general)]], con <code>sprite = 1</code>. X y <code>!SpriteIndex</code> deben identificar al mismo sprite al entrar. Conserva Y y <code>$02-$04</code> de su resultado si vas a concatenar un efecto. Incluye <code>RTL</code>.

<code>%StandardSpritePaletteAssignmentNoUpload()</code> utiliza las variables del tipo de sprite seleccionado para asignar la paleta, dejando pendiente la carga de los colores.

'''Parámetros y entradas'''

<pre>
%StandardSpritePaletteAssignmentNoUpload(type, manualIDGroup, manualID)
</pre>

Recibe los mismos parámetros y datos que <code>%StandardSpritePaletteAssignment()</code>. A debe contener el offset de la tabla de paletas con 16 bits.

'''Resultado'''

El mismo que <code>!PaletteAssignmentNoUpload</code>: guarda la paleta asignada y devuelve el carry, Y, el ID en <code>$00-$01</code> y la dirección en <code>$02-$04</code>, con las condiciones indicadas en esa entrada.

La macro ya incluye un <code>RTL</code>. Llama a la rutina del ejemplo con <code>JSL AssignPaletteForEffect</code>. El código que aplica el efecto va después de esa llamada.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
AssignPaletteForEffect:
REP #$20
LDA #!MySpritePaletteTableOffset
%StandardSpritePaletteAssignmentNoUpload("Normal", #$FE, "!CustomSpriteNumber,x")
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

==== ReplacePalette (macro general) ====

'''Registros y memoria temporal:''' entra con A, X e Y de 8 bits y con el puntero de origen preparado en <code>$02-$04</code>. A e Y pueden cambiar; con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code>; con <code>sprite = 0</code>, no se conserva X. Los tres quedan en 8 bits. Puede sobrescribir <code>$00-$01</code> y los temporales de efectos cuando corresponda. Conserva DBR y D. Termina con <code>RTL</code>.

<code>%ReplacePalette()</code> sustituye los colores de una paleta que ya estás usando. Hace lo mismo que <code>!ReplacePalette</code>, pero tú eliges qué variables leer. Si otros sprites o códigos usan esa misma paleta, también verán los nuevos colores.

Suele utilizarse después de una asignación sin carga, como <code>%PaletteAssignmentNoUpload()</code>. Primero obtienes la paleta asignada y después preparas en <code>$02-$04</code> la dirección de los colores que quieres usar para reemplazarla.

'''Parámetros y entradas'''

<pre>
%ReplacePalette(sprite, paletteOption, palette)
</pre>

* <code>sprite</code>: 1 obtiene el índice del sprite desde <code>!SpriteIndex</code>; 0 utiliza variables independientes de ese índice.
* <code>paletteOption</code>: variable o valor de las opciones de paleta. El bit <code>$80</code> indica si se aplica el efecto global.
* <code>palette</code>: variable o valor de la paleta de destino, entre <code>$00</code> y <code>$0E</code> de dos en dos.
* <code>$02-$04</code>: dirección ROM de los nuevos colores en BGR555.
* A en modo de 8 bits.

'''Resultado'''

Cambia los colores sin cambiar el ID de asignación. Devuelve el carry activado cuando hay colores con los que se puede dibujar, incluidos los anteriores si el cambio todavía no se pudo completar. El carry queda desactivado si todavía no hay un resultado disponible.

Llámala cuando cambien los colores que quieres mostrar. Repetir la llamada cada frame obliga a preparar de nuevo la paleta y sus efectos.

Llama a la rutina del ejemplo con <code>JSL ReplaceSpritePalette</code>. La macro ya incluye el <code>RTL</code> que termina la rutina.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
ReplaceSpritePalette:
LDA.b #!PaletteMyAlternatePalette
STA $02
LDA.b #!PaletteMyAlternatePalette>>8
STA $03
LDA.b #!PaletteMyAlternatePalette>>16
STA $04
%ReplacePalette(1, "!NormalPaletteOption,x", "!NormalPalette,x")
</pre>

<code>!PaletteMyAlternatePalette</code> es la dirección de una paleta insertada a partir de los recursos del DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza eliminando separadores y poniendo en mayúscula la inicial de cada palabra: <code>my_alternate_palette</code> pasa a <code>MyAlternatePalette</code>.

==== Cargar colores con TransferPalette ====

Estas macros cargan colores en la paleta que tú elijas, sin asignación automática. Puedes usarlas para cambiar una paleta de fondo, una paleta reservada para un sprite o colores preparados en RAM.

A diferencia de las macros de transferencia de PPU, también actualizan las copias de colores que necesita el juego y preparan el estado de los efectos. No hace falta copiar los buffers ni invalidar sus indicadores a mano.

'''Parámetros comunes'''

* <code>CGRAMOffset</code>: primer color que se cambiará, entre <code>$00</code> y <code>$FF</code>. Es un operando de 8 bits: <code>#$91</code> empieza en el color 1 de la paleta 9; <code>$00</code> utiliza el número guardado en esa scratch.
* <code>Length</code>: cantidad de bytes que se copiarán. Es un valor conocido al ensamblar, '''sin <code>#</code>''': <code>$001E</code> copia 15 colores. Debe ser mayor que cero y par, y la carga no debe pasar del último color de CGRAM.
* <code>GlobalEffect</code>: utiliza <code>0</code> para cargar sin efecto global o <code>1</code> para que la paleta reciba el efecto global. Es una opción fija de la llamada, no una variable de RAM.

'''Qué hace GlobalEffect'''

{| class="wikitable"
! Valor !! Comportamiento
|-
| <code>0</code> || Programa la transferencia de los colores sin efecto y actualiza los buffers de SMW y Dynamic Xtreme. Si los efectos están habilitados, excluye del efecto global las paletas modificadas.
|-
| <code>1</code> || Guarda los colores originales para que el sistema les aplique el efecto global antes de cargarlos. Registra las paletas modificadas para recibirlo y borra los indicadores de sus efectos anteriores.
|}

Con <code>GlobalEffect = 1</code> no se carga primero una versión sin efecto: se espera al resultado del sistema de efectos. Esto también sirve para dejar preparada una paleta cuando el ID del efecto global todavía es 0. Si los efectos de paleta están deshabilitados en la instalación, la llamada utiliza la carga directa.

Estas opciones afectan a cada paleta de 16 colores que toque la carga, no solo a los colores copiados. Para una carga con efecto global, proporciona todos los colores visibles de las paletas que cambies: por ejemplo, los 15 colores de una paleta de sprites, comenzando en su color 1. No uses una carga parcial para conservar otros colores originales que todavía no hayas preparado.

'''Entradas y resultado comunes'''

* Entra con A, X e Y en modo de 8 bits. D debe ser <code>$0000</code> en LoROM o <code>$3000</code> en el contexto habitual de SA-1 Pack. DBR debe permitir acceder al buffer de paletas de SMW: <code>$0703</code> en LoROM o su espejo <code>$6703</code> en SA-1. Los bancos habituales con espejos de RAM, como <code>$00-$3F</code> y <code>$80-$BF</code>, permiten esos accesos. Si pasas tablas con direcciones de 16 bits, DBR también debe permitir leerlas.
* Carry activado: la transferencia directa fue aceptada o los colores originales quedaron preparados para el efecto global. En este último caso, no significa que el resultado ya se haya cargado a pantalla.
* Carry desactivado: no se aceptó la transferencia directa por el límite de datos del frame. Puedes volver a intentarlo más adelante; no se actualizan los buffers ni los indicadores de efectos de esa carga.
* A y X pueden cambiar, tanto en éxito como en fallo. Y puede cambiar si se copian colores; no lo utilices para conservar otro dato entre llamadas. Los tres quedan en modo de 8 bits en ambos resultados. Conservan DBR y D.
* Las llamadas pueden modificar <code>$68-$6D</code> cuando están habilitados los efectos; las variantes <code>FromAddress</code>, <code>FromTable</code> y <code>Resource</code>, incluida <code>ResourceWithLength</code>, también utilizan <code>$65-$67</code>. No coloques el puntero de origen ni el color de destino en scratch que la propia llamada vaya a sobrescribir antes de terminar de utilizarlos.
* No incluyen <code>RTS</code> ni <code>RTL</code>: el código continúa después de la macro.

Si el origen está en RAM, conserva sus datos hasta que se ejecute la transferencia programada. El bloque de origen tampoco debe cruzar el final de su banco. Para <code>CGRAMOffset</code>, utiliza un inmediato o una variable que siga siendo válida después de que la macro cambie X e Y; evita operandos indexados con esos registros.

Llama a estas macros cuando quieras cambiar los colores, no en cada frame si la paleta sigue siendo la misma. Si utilizas una paleta de sprites con un destino fijo, resérvala para que la asignación automática no la utilice.

==== TransferPaletteFromAddress ====

<code>%TransferPaletteFromAddress()</code> carga colores desde una dirección conocida al ensamblar. Puede ser un label de tu código o un define con la dirección completa del recurso.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromAddress(Address, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Address</code>: dirección de origen completa, sin <code>#</code>.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; Paleta 9, colores 1-F, con efecto global.
%TransferPaletteFromAddress(!PaletteMyPalette, #$91, $001E, 1)
</pre>

<code>!PaletteMyPalette</code> se genera al instalar una paleta declarada en <code>Palettes</code> de un DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre usa PascalCase: se eliminan espacios, guiones bajos y guiones, y se pone en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_palette</code> pasa a <code>MyPalette</code>.

==== TransferPaletteFromPointer ====

<code>%TransferPaletteFromPointer()</code> utiliza una dirección de origen que ya está guardada en tres bytes consecutivos de scratch. Es útil si tu código elige la paleta durante el juego.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromPointer(Pointer, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Pointer</code>: dirección del primer byte de la scratch, sin <code>#</code>. Los tres bytes deben contener la dirección de origen en orden bajo, alto y banco. Por ejemplo, <code>$02</code> utiliza <code>$02-$04</code>.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; Preparar la dirección de la paleta en $02-$04.
REP #$20
LDA.w #!PaletteMyPalette
STA $02
SEP #$20
LDA.b #!PaletteMyPalette>>16
STA $04

; Paleta 9, colores 1-F, sin efecto global.
%TransferPaletteFromPointer($02, #$91, $001E, 0)
</pre>

<code>!PaletteMyPalette</code> se genera desde una paleta del DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase eliminando separadores: <code>my_palette</code> se convierte en <code>MyPalette</code>.

==== TransferPaletteFromTable ====

<code>%TransferPaletteFromTable()</code> permite indicar por separado los dos bytes de dirección y el byte de banco del origen. Puedes obtenerlos de tablas, variables o valores inmediatos. La macro reúne esos datos en <code>$65-$67</code>.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromTable(TableAddr, TableBNK, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>TableAddr</code>: operando que se lee con A de 16 bits para obtener los dos bytes de dirección.
* <code>TableBNK</code>: operando que se lee con A de 8 bits para obtener el banco.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; $02-$03 contiene la dirección y $04 contiene el banco.
%TransferPaletteFromTable("$02", "$04", #$91, $001E, 1)
</pre>

A diferencia de <code>FromPointer</code>, los operandos de dirección y banco no tienen que estar en posiciones consecutivas. Si los lees desde tablas del código, el banco de datos debe permitir acceder a ellas.

==== TransferPaletteResource ====

<code>%TransferPaletteResource()</code> carga una paleta registrada en el DynamicInfo utilizando su tamaño completo. No necesitas escribir su dirección ni su cantidad de bytes.

'''Parámetros'''

<pre>
%TransferPaletteResource(Name, CGRAMOffset, GlobalEffect)
</pre>

* <code>Name</code>: nombre normalizado de la paleta, sin prefijo <code>!Palette</code> y sin extensión. La macro utiliza <code>!Palette<Name></code> y <code>!Palette<Name>Size</code>.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; MyPalette contiene 15 colores.
%TransferPaletteResource(MyPalette, #$91, 1)
BCS .Accepted
; No se aceptó la carga directa: volver a intentarlo después.
RTL
.Accepted
; Continuar con el resto del código.
</pre>

El ejemplo continúa en <code>.Accepted</code> si se aceptó la carga directa o se prepararon los colores para el efecto global. El <code>RTL</code> pertenece al ejemplo, no a la macro.

<code>MyPalette</code> corresponde a los defines <code>!PaletteMyPalette</code> y <code>!PaletteMyPaletteSize</code>, generados en <code>DXDefines.asm</code> desde la sección <code>Palettes</code> del DynamicInfo. El nombre usa PascalCase eliminando espacios, guiones bajos y guiones: <code>my_palette</code> pasa a <code>MyPalette</code>. Esta llamada no utiliza los defines <code>!Resource...</code> de la sección <code>Resources</code> ni las paletas convertidas RGB/HSL de un <code>*.paleffect</code>.

==== TransferPaletteResourceWithLength ====

<code>%TransferPaletteResourceWithLength()</code> utiliza la dirección de una paleta registrada, pero permite copiar solo la cantidad de bytes que indiques.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteResourceWithLength(Name, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Name</code>: nombre normalizado de la paleta, igual que en <code>%TransferPaletteResource()</code>.
* <code>Length</code>: cantidad de bytes que se copiarán, sin <code>#</code>. No debe superar el tamaño del recurso.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; Copiar 4 colores al comienzo de la paleta 9, sin efecto global.
%TransferPaletteResourceWithLength(MyPalette, #$90, $0008, 0)
</pre>

<code>MyPalette</code> utiliza el define <code>!PaletteMyPalette</code>, generado desde una paleta del DynamicInfo y publicado en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_palette</code> se convierte en <code>MyPalette</code>.

<code>TransferPaletteCommon</code> y <code>TransferPaletteData</code> son las partes internas que comparten estas llamadas. Para cargar paletas desde tu código, utiliza las variantes anteriores, que también preparan el estado de los efectos.

=== Efectos de paleta ===

Estas macros permiten modificar los colores de una paleta: teñirla, cambiar su brillo, pasar de una paleta a otra o aplicar un efecto guardado en un archivo <code>*.paleffect</code>.

Para ver ejemplos completos, consulta [[es/Dynamic_Xtreme_UberASM_guide#Aplicar un efecto global de paleta|Aplicar un efecto global de paleta]] en la guía de UberASM, con ejemplos de un efecto fijo, un ciclo y una transición. El apartado [[es/Dynamic_Xtreme_UberASM_guide#Cambiar paletas durante el juego|Cambiar paletas durante el juego]] muestra cómo cargar los colores con <code>TransferPalette</code> y comprobar si la llamada fue aceptada.

RGB trabaja con rojo, verde y azul. HSL trabaja con tono, saturación y luminosidad. Elige las macros RGB o HSL según el cambio que quieras realizar. Para conocer los efectos disponibles, consulta [[es/Dynamic_Xtreme_files_and_formats#Tipos_de_efectos|Tipos de efectos]].

'''¿Qué llamada necesitas?'''

{| class="wikitable"
! Quieres… !! Utiliza…
|-
| Teñir una paleta o cambiar su tono, saturación o luminosidad. || <code>Mix</code> / <code>MixAndMerge</code>.
|-
| Pasar de una paleta a otra. || <code>PaletteTransition</code>.
|-
| Aplicar un efecto que ya definiste en un archivo <code>*.paleffect</code>. || <code>DoEffect</code> / <code>DoEffectAndMerge</code>.
|-
| Darle un efecto propio a un sprite y conservar además el efecto global. || <code>ConcatenateRGBPaletteEffectToGlobal</code> o su variante HSL, después de asignar la paleta sin carga.
|}

Para calcular un efecto directamente, el proceso habitual es preparar los colores originales con <code>SetRGBBase</code> o <code>SetHSLBase</code> y después aplicar el cambio. Los ejemplos utilizan las variantes <code>Default</code>, que trabajan con las copias de paleta de Dynamic Xtreme y evitan escribir direcciones de memoria.

Las variantes <code>AndMerge</code> dejan los colores en el formato que necesita SNES para mostrarlos. Aun así, calcularlos no los envía automáticamente a la pantalla: la carga se completa mediante el manejo de paletas o las transferencias a CGRAM. Si estás usando las rutinas de concatenación después de <code>PaletteAssignmentNoUpload</code>, estas ya se encargan de preparar los colores y completar su carga.

En los ejemplos, prepara A en modo de 8 bits antes de llamar a las macros.

'''Registros y memoria temporal de los efectos'''

* Las macros de preparación de bases, mezcla, transición, conversión y <code>DoEffect</code> entran con A, X e Y de 8 bits. Sus variantes <code>Default</code> utilizan el mismo contrato. Las macros de concatenación tienen una entrada diferente, descrita en su apartado.
* Las macros anteriores preparan sus argumentos y llaman internamente a la rutina del parche. Al terminar continúan en la instrucción siguiente: no incluyen un retorno que termine tu rutina.
* A, X e Y deben tratarse como temporales y quedan en 8 bits al volver. No se devuelve éxito o fallo en carry: el resultado son los colores escritos en el buffer de destino. Conservan DBR y D conforme a las reglas de [[#Estado del CPU y memoria temporal|estado del CPU]].
* Pueden sobrescribir <code>$00-$0F</code>, <code>$45-$54</code>, <code>$6A</code>, <code>$8A-$8F</code> y <code>$D5-$D7</code>, según la operación. Allí se preparan punteros, longitudes, canales y ratios; no guardes en ese espacio valores que deban sobrevivir a la llamada.
* Los bancos de origen y destino se leen con A de 8 bits; las direcciones, offsets y cantidades de colores se leen con A de 16 bits durante la preparación. Los canales y ratios se leen con A de 8 bits. El ID de <code>DoEffect</code> se lee con A de 16 bits. Prepara los operandos de memoria con el tamaño correspondiente.
* Si tus operandos están indexados, X e Y deben identificar sus datos al entrar. Su valor puede cambiar dentro de la llamada. Las variantes completas también deben evitar que sus argumentos se solapen con los temporales que se preparan antes de leerlos.

==== Preparar los colores: SetRGBBase y SetHSLBase ====

Antes de modificar los colores, necesitas una copia con la que calcular el efecto. <code>%SetRGBBase()</code> prepara esa copia para efectos RGB; <code>%SetHSLBase()</code> la prepara para HSL. Si los colores originales no cambiaron, puedes reutilizarla en los siguientes frames.

En las variantes <code>Default</code> solo indicas el primer color y cuántos colores quieres preparar:

<pre>
%SetRGBBaseDefault(offset, length)
%SetHSLBaseDefault(offset, length)
</pre>

<code>offset</code> es el número del primer color y <code>length</code> es la cantidad. Por ejemplo, <code>#$0081</code> y <code>#$000F</code> seleccionan los 15 colores visibles de la paleta 8.

Si necesitas elegir tú las direcciones donde leer y guardar los colores, utiliza las versiones completas:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%SetRGBBase(src, srcbnk, dst, dstbnk, offset, length)
%SetHSLBase(src, srcbnk, dst, dstbnk, offset, length)
</pre>

Las variantes <code>%SetRGBBaseDefault(offset, length)</code> y <code>%SetHSLBaseDefault(offset, length)</code> leen de <code>DX_PPU_CGRAM_PaletteCopy</code> y guardan el resultado en <code>DX_PPU_CGRAM_BaseRGBPalette</code> o <code>DX_PPU_CGRAM_BaseHSLPalette</code>.

'''Ejemplo: preparar una paleta de sprites'''

<pre>
; Paleta 8, sin incluir su primer color transparente.
%SetRGBBaseDefault(#$0081, #$000F)

; Para trabajar en HSL, utiliza esta variante en su lugar:
; %SetHSLBaseDefault(#$0081, #$000F)
</pre>

<code>$81</code> es el segundo color de la paleta 8: la paleta comienza en el color <code>$80</code> y se procesan los 15 siguientes.

==== Mezclar colores: Mix y MixAndMerge ====

Estas macros acercan los colores originales a los valores que indiques. Por ejemplo, puedes llevar el rojo a 31 y el verde y azul a 0 para teñir de rojo una paleta. Al cambiar poco a poco los ratios, el efecto aparece gradualmente.

Los parámetros <code>v</code> indican el color que quieres alcanzar, entre 0 y 31. Los parámetros <code>r</code> indican cuánto acercarse a ese color: 0 conserva el original, 127 aplica el cambio completo y 64 lo aplica aproximadamente a la mitad. En los ejemplos se escriben como <code>#$00</code>, <code>#$7F</code> y <code>#$40</code>.

Para RGB, los valores 1, 2 y 3 corresponden a rojo, verde y azul. Para HSL corresponden a tono, saturación y luminosidad.

El final del nombre indica qué componentes se modifican:

{| class="wikitable"
! RGB !! HSL !! Componentes modificados
|-
| <code>R</code>, <code>G</code>, <code>B</code> || <code>H</code>, <code>S</code>, <code>L</code> || Uno.
|-
| <code>RG</code>, <code>RB</code>, <code>GB</code> || <code>HS</code>, <code>HL</code>, <code>SL</code> || Dos.
|-
| <code>RGB</code> || <code>HSL</code> || Los tres.
|}

Cada combinación está disponible como <code>Mix...</code>, <code>MixAndMerge...</code> y <code>MixAndMerge...Default</code>. Por ejemplo: <code>%MixR()</code>, <code>%MixAndMergeR()</code> y <code>%MixAndMergeRDefault()</code>.

Primero se entregan los ratios de los componentes elegidos y después sus valores nuevos, en el orden del nombre. Al final van las direcciones de origen y destino, el primer color y la cantidad. Las variantes <code>Default</code> omiten las direcciones.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%MixRGB(r1, r2, r3, v1, v2, v3, src, srcbnk, dst, dstbnk, offset, length)
%MixAndMergeRG(r1, r2, v1, v2, src, srcbnk, dst, dstbnk, offset, length)
%MixAndMergeLDefault(r3, v3, offset, length)
</pre>

'''Ejemplo RGB: teñir de rojo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Preparar los colores originales de la paleta 8.
%SetRGBBaseDefault(#$0081, #$000F)

; Acercar los tres componentes a un rojo puro, aproximadamente a la mitad.
%MixAndMergeRGBDefault(#$40, #$40, #$40, #$1F, #$00, #$00, #$0081, #$000F)

</pre>

Los tres primeros valores <code>#$40</code> indican la intensidad del cambio para rojo, verde y azul. Los siguientes, <code>#$1F, #$00, #$00</code>, indican el rojo puro al que se acercarán. Los dos últimos seleccionan los 15 colores de la paleta 8.

'''Ejemplo HSL: aclarar la paleta'''

<pre>
%SetHSLBaseDefault(#$0081, #$000F)
%MixAndMergeLDefault(#$40, #$1F, #$0081, #$000F)
</pre>

Aquí solo cambia la luminosidad: <code>#$40</code> aplica aproximadamente la mitad del cambio y <code>#$1F</code> indica la luminosidad máxima. Este es un ejemplo independiente del anterior.

==== Cambiar entre paletas: PaletteTransition ====

Estas macros acercan cada color de la paleta original al color correspondiente de otra paleta. A diferencia de <code>Mix</code>, cada color tiene su propio destino. Sirven, por ejemplo, para pasar de los colores normales de un sprite a una paleta de daño.

Las variantes son <code>PaletteTransitionRGB</code>, <code>PaletteTransitionHSL</code>, <code>PaletteTransitionRGBAndMerge</code> y <code>PaletteTransitionHSLAndMerge</code>. Las dos variantes <code>AndMerge</code> también tienen versión <code>Default</code>.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteTransitionRGB(r1, r2, r3, src, srcbnk, targetpal, targetpalbnk, dst, dstbnk, offset, length)
%PaletteTransitionHSLAndMerge(r1, r2, r3, src, srcbnk, targetpal, targetpalbnk, dst, dstbnk, offset, length)
%PaletteTransitionRGBAndMergeDefault(r1, r2, r3, targetpal, targetpalbnk, offset, length)
</pre>

<code>targetpal</code> y <code>targetpalbnk</code> indican la dirección y el banco de la paleta de destino. Debe estar preparada con 3 bytes por color, en RGB o HSL según la macro. Los ratios controlan cuánto se acerca cada componente al color de destino.

'''Ejemplo: calcular un paso intermedio de una transición'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Este ejemplo trabaja con los primeros 15 colores de la copia de paletas.
%SetRGBBaseDefault(#$0000, #$000F)
%PaletteTransitionRGBAndMergeDefault(#$40, #$40, #$40, #!PaletteMyTargetRGB, #!PaletteMyTargetRGB>>16, #$0000, #$000F)
</pre>

El ejemplo supone que <code>!PaletteMyTargetRGB</code> corresponde a una paleta de destino RGB generada al instalar un <code>*.paleffect</code> de transición. Su dirección queda en <code>DXDefines.asm</code>. El nombre se normaliza eliminando espacios, guiones y guiones bajos y poniendo en mayúscula la inicial de cada palabra: <code>my_target</code> pasa a <code>MyTarget</code>. Para HSL se utiliza la paleta convertida a HSL y la macro correspondiente.

==== Aplicar un efecto de un archivo: DoEffect ====

<code>%DoEffect()</code> aplica un efecto de un archivo <code>*.paleffect</code> mediante su ID. El archivo ya contiene el tipo de efecto, los valores de color y los ratios, por lo que no necesitas entregarlos uno por uno.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%DoEffect(effect, src, srcbnk, dst, dstbnk, offset, length)
%DoEffectAndMerge(effect, src, srcbnk, dst, dstbnk, offset, length)
%DoEffectAndMergeDefaultRGB(effect, offset, length)
%DoEffectAndMergeDefaultHSL(effect, offset, length)
</pre>

* <code>effect</code>: ID del efecto, como <code>#!PaletteEffectIDMyEffect0</code>.
* El origen debe contener colores RGB o HSL separados, según el efecto elegido.
* <code>DoEffect</code> guarda el resultado con 3 bytes por color para poder seguir modificándolo.
* <code>DoEffectAndMerge</code> guarda colores en formato de SNES. Las variantes <code>DefaultRGB</code> y <code>DefaultHSL</code> eligen la base correspondiente y escriben en <code>DX_PPU_CGRAM_PaletteWriteMirror</code>.

'''Ejemplo: aplicar un efecto RGB a la paleta 8'''

<pre>
%SetRGBBaseDefault(#$0081, #$000F)
%DoEffectAndMergeDefaultRGB(#!PaletteEffectIDMyEffect0, #$81, #$000F)
</pre>

<code>!PaletteEffectIDMyEffect0</code> se genera desde un archivo <code>*.paleffect</code> y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_effect</code> pasa a <code>MyEffect</code>. El número final identifica el efecto dentro del archivo. Si el efecto trabaja en HSL, prepara la base HSL y utiliza <code>%DoEffectAndMergeDefaultHSL()</code>.

==== Convertir entre RGB y HSL ====

<code>%RGBToHSL()</code> convierte colores RGB a HSL y <code>%HSLToRGB()</code> hace el cambio contrario. Ambas leen y escriben 3 bytes por color. Sirven cuando necesitas continuar modificando una paleta con un efecto que usa el otro sistema de color.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%RGBToHSL(src, srcbnk, dst, dstbnk, offset, length)
%HSLToRGB(src, srcbnk, dst, dstbnk, offset, length)
</pre>

'''Ejemplo: convertir la base RGB a HSL'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%RGBToHSL(#DX_PPU_CGRAM_BaseRGBPalette, #DX_PPU_CGRAM_BaseRGBPalette>>16, #DX_PPU_CGRAM_BaseHSLPalette, #DX_PPU_CGRAM_BaseHSLPalette>>16, #$0081, #$000F)
</pre>

El ejemplo lee los 15 colores de la paleta 8 de la base RGB y guarda su equivalente en la base HSL. La base RGB debe estar preparada antes de llamar a la conversión.

==== Combinar un efecto propio con el global ====

'''Registros y memoria temporal:''' estas dos macros entran con A de 16 bits, X de 8 bits con el valor de la paleta y Y de 8 bits con el resultado de la asignación sin carga. Al volver los tres quedan en 8 bits. Con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code>; con <code>sprite = 0</code>, no se conserva X. A e Y pueden cambiar. Utilizan los temporales de efectos y <code>$F0-$F3</code>. Conservan DBR y D. A diferencia de las demás macros de efectos, incluyen <code>RTL</code> y devuelven disponibilidad mediante carry, también cuando reutilizan un resultado anterior.

<code>%ConcatenateRGBPaletteEffectToGlobal()</code> y <code>%ConcatenateHSLPaletteEffectToGlobal()</code> permiten aplicar un efecto propio a una paleta que también debe recibir el efecto global. Son las macros utilizadas por las llamadas para sprites del mismo nombre, pero permiten elegir las variables de paleta.

Suelen utilizarse después de <code>%PaletteAssignmentNoUpload()</code> o su variante para sprites: primero se asigna la paleta sin cargar los colores y después se aplican los efectos. Conserva los datos devueltos por la asignación para esta segunda llamada.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%ConcatenateRGBPaletteEffectToGlobal(sprite, paletteOption, palette)
%ConcatenateHSLPaletteEffectToGlobal(sprite, paletteOption, palette)
</pre>

* <code>sprite</code>: 1 recupera el índice del sprite desde <code>!SpriteIndex</code>; 0 permite utilizar variables propias.
* <code>paletteOption</code>: variable o valor de las opciones de paleta; activa el bit <code>$80</code> para incluir el efecto global.
* <code>palette</code>: variable que contiene la paleta asignada, entre <code>$00</code> y <code>$0E</code> de dos en dos.
* A de 16 bits: ID del efecto local RGB o HSL, según la macro.
* X de 8 bits: copia del valor de la paleta asignada.
* Y de 8 bits: conserva el valor devuelto por la asignación sin carga.
* <code>$02-$04</code>: dirección de los colores originales preparada por esa asignación.

Devuelven el carry activado si se puede dibujar con el efecto solicitado o con el anterior mientras se prepara el nuevo. Si todavía no hay un resultado disponible, el carry queda desactivado. Estas dos macros ya terminan la rutina con <code>RTL</code>.

'''Ejemplo: completar una asignación sin carga'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Llamar esta rutina con JSL después de asignar la paleta sin carga.
; Deben conservarse Y y $02-$04 de aquella llamada.
ApplyLocalEffect:
LDA !NormalPalette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyEffect0
%ConcatenateRGBPaletteEffectToGlobal(1, "!NormalPaletteOption,x", "!NormalPalette,x")
</pre>

<code>!PaletteEffectIDMyEffect0</code> se genera desde un <code>*.paleffect</code> y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_effect</code> pasa a <code>MyEffect</code>. Para un efecto HSL, utiliza la macro HSL. Si usas Y para leer una tabla de efectos, guarda su valor con <code>PHY</code> y recupéralo con <code>PLY</code> antes de concatenar.

==== Elegir las direcciones y combinar varios efectos ====

Las variantes <code>Default</code> de los ejemplos eligen las direcciones por ti. Si necesitas guardar los resultados en otro lugar o aplicar varios efectos seguidos, utiliza las versiones completas. Estos son los parámetros de dirección que aparecen en ellas:

* <code>src</code>: dónde leer los colores originales; <code>srcbnk</code>: su banco.
* <code>dst</code>: dónde guardar el resultado; <code>dstbnk</code>: su banco. El destino debe ser un espacio de RAM que tu código pueda utilizar.
* <code>offset</code>: primer color que se procesará, contando desde 0.
* <code>length</code>: cantidad de colores que se procesarán.

Para indicar una dirección fija, se utiliza <code>#Nombre</code> para la dirección y <code>#Nombre>>16</code> para su banco, como en el ejemplo de conversión RGB a HSL. También puedes pasar variables que contengan esos datos.

El espacio necesario depende del paso que estés realizando:

{| class="wikitable"
! Operación !! Lee !! Guarda
|-
| <code>SetRGBBase</code> / <code>SetHSLBase</code> || Paleta normal: 2 bytes por color. || Colores separados: 3 bytes por color.
|-
| <code>Mix</code>, <code>PaletteTransition</code>, <code>DoEffect</code> sin <code>AndMerge</code> || Colores separados: 3 bytes por color. || Colores separados: 3 bytes por color.
|-
| Variantes <code>AndMerge</code> || Colores separados: 3 bytes por color. || Paleta normal: 2 bytes por color.
|-
| <code>RGBToHSL</code> / <code>HSLToRGB</code> || Colores separados: 3 bytes por color. || Colores separados: 3 bytes por color.
|}

Por ejemplo, si quieres aplicar dos efectos seguidos, el primero debe guardar sus colores separados, sin <code>AndMerge</code>. El segundo lee ese resultado y utiliza <code>AndMerge</code> para dejar la paleta lista para cargarla. Si uno trabaja en RGB y el otro en HSL, convierte los colores entre ambos pasos.

Las macros utilizan memoria temporal, entre otras las direcciones <code>$45-$50</code>, <code>$51-$53</code>, <code>$6A</code>, <code>$8A</code>, <code>$8C</code>, <code>$8E</code>, <code>$0E-$0F</code> y <code>$D5-$D7</code>, según la operación. No guardes en ellas datos que necesites conservar después de la llamada.

=== PPU ===

Estas macros permiten cargar gráficos en VRAM y colores en CGRAM. VRAM es la memoria donde SNES guarda los gráficos que muestra; CGRAM guarda sus paletas.

La llamada deja anotada una transferencia para el próximo NMI, cuando el juego puede actualizar esas memorias. No hace la copia inmediatamente. Los datos de origen deben seguir disponibles hasta que se realice la transferencia.

'''Qué llamada elegir'''

{| class="wikitable"
! Necesitas… !! VRAM !! CGRAM
|-
| Indicar la dirección de origen y su banco por separado. || <code>TransferToVRAM</code> || <code>TransferToCGRAM</code>
|-
| Indicar una dirección completa y dejar que la macro obtenga el banco. || <code>TransferToVRAMFromAddr</code> || <code>TransferToCGRAMFromAddr</code>
|-
| Cargar un recurso completo registrado en Dynamic Xtreme. || <code>TransferResourceToVRAM</code> || <code>TransferResourceToCGRAM</code>
|-
| Cargar solo una cantidad de bytes de un recurso. || <code>TransferResourceToVRAMWithLenght</code> || <code>TransferResourceToCGRAMWithLenght</code>
|}

Las versiones normales comprueban si la transferencia cabe dentro del límite de bytes del frame:

* Carry activado: la transferencia quedó programada.
* Carry desactivado: no se programó porque superaría ese límite. Tu código puede intentarlo en otro frame.

Este límite se comparte con las demás cargas de Dynamic Xtreme. Programar varias copias en un frame consume parte del mismo límite. Estas macros modifican A y X. Al aceptar la transferencia dejan A, X e Y en modo de 8 bits; si la rechazan, dejan A en 8 bits, pero no cambian necesariamente el modo de X e Y.

'''Límites y condiciones de las transferencias'''

Antes de preparar las entradas, ten en cuenta estos límites:

'''Presupuesto de bytes y capacidad de las listas'''

{| class="wikitable"
! Límite !! Qué controla !! Valor predeterminado
|-
| <code>DX_Dynamic_MaxDataPerFrame</code>
| Cantidad total de bytes que se permite solicitar durante un frame. Se compara con <code>DX_Dynamic_CurrentDataSend</code>, que acumula los bytes solicitados por los distintos recursos.
| <code>$0800</code> bytes, compartidos entre las cargas de Dynamic Xtreme.
|-
| Lista de VRAM
| Cantidad de solicitudes que caben en sus tablas. Cada entrada utiliza dos bytes por tabla; <code>!VRAMTransferSize</code> reserva la cantidad de bytes de cada una.
| <code>!VRAMTransferSize = 64</code>: espacio para '''32 solicitudes'''.
|-
| Lista de CGRAM
| Cantidad de solicitudes que caben en sus tablas. <code>!CGRAMTransferSize</code> determina la cantidad de entradas disponibles.
| <code>!CGRAMTransferSize = 64</code>: espacio para '''64 solicitudes'''.
|}

Son límites diferentes. Por ejemplo, 32 transferencias de 2 bytes a VRAM solo solicitan 64 bytes, pero ya ocupan las 32 entradas de la lista predeterminada. No puedes añadir otra solo porque todavía quede presupuesto de bytes.

Las macros normales comprueban '''el presupuesto de bytes''', pero '''no comprueban si queda una entrada libre en la lista'''. Si la lista está llena, debes posponer la solicitud desde tu código. Añadirla de todos modos puede escribir fuera de las tablas y corromper otras variables; no se devuelve un fallo específico por lista llena. Cuenta también las solicitudes de otros sistemas: una pose dinámica puede necesitar varias transferencias.

Las variantes <code>Forced</code> omiten la comprobación del presupuesto de bytes y suman la cantidad solicitada a <code>DX_Dynamic_CurrentDataSend</code>. No aumentan la capacidad de las listas ni el tiempo disponible para transferencias. Los contadores de las listas son de 8 bits y el de bytes es de 16 bits: no permitas que se desborden.

'''Condiciones que debe cumplir la transferencia'''

{| class="wikitable"
! Dato !! Responsabilidad de tu código
|-
| Longitud
| Utiliza una cantidad de bytes '''mayor que cero y par'''. En DMA, <code>$0000</code> significa 65536 bytes, no una copia vacía. Las macros de PPU no comprueban estas condiciones.
|-
| Origen
| La cantidad solicitada debe existir en el recurso o buffer y no debe cruzar el final de su banco. El DMA no continúa automáticamente en el banco siguiente. Divide la carga si necesitas cruzarlo.
|-
| Origen en RAM
| Debes conservar el contenido del buffer hasta que NMI ejecute la transferencia. La lista guarda su dirección, no una copia de los datos. En SA-1, utiliza memoria que también pueda leer el S-CPU, que realiza la transferencia.
|-
| Destino en VRAM
| La dirección se expresa en palabras de 2 bytes. Tanto el inicio como el final de la carga deben quedar dentro de <code>$0000–$7FFF</code> y en el espacio gráfico que tu recurso puede utilizar. Por ejemplo, <code>$0200</code> bytes desde <code>$6000</code> ocupan las palabras <code>$6000–$60FF</code>.
|-
| Destino en CGRAM
| El destino indica el primer color. Cada color ocupa 2 bytes; la carga no debe pasar del color <code>$FF</code>. Por ejemplo, desde <code>$F1</code> caben 15 colores, es decir, <code>$001E</code> bytes.
|}

El carry activado de una macro normal indica que aceptó la solicitud según el presupuesto de bytes; no confirma que haya validado el origen, el destino, la longitud o la capacidad de la lista. Estas condiciones también se aplican a las variantes <code>Forced</code>.

Para cambiar colores conservando las copias de paleta de SMW y el estado de los efectos, utiliza [[#Cargar colores con TransferPalette|TransferPalette]]. Las transferencias de PPU a CGRAM solo programan la copia.

'''Estado de los registros'''

* Entra con A, X e Y en 8 bits. Las versiones normales establecen internamente A de 16 bits para comprobar el presupuesto, pero este estado de entrada también permite utilizar las variantes <code>Forced</code>, especialmente las de CGRAM.
* Al aceptar la transferencia, A y X cambian y los tres registros quedan en 8 bits. Y no se utiliza como registro de trabajo, pero pierde su byte alto si entrabas con índices de 16 bits. Al rechazarla, A cambia y queda en 8 bits; X e Y conservan sus valores y el tamaño que tenían al entrar.
* No utilizan scratch para preparar la solicitud. Escriben en las listas de transferencias y en el contador de bytes del frame. Conservan DBR y D. DBR debe permitir acceder al contador; las variantes también pueden necesitar ese banco para leer los operandos de memoria que tú entregues.
* Las direcciones de origen y las longitudes se leen con A de 16 bits. El destino de VRAM y su argumento de banco se leen con A de 16 bits; el banco debe proporcionarse como un valor de 16 bits cuyo byte alto sea cero. En CGRAM, el banco de origen y el color de destino se leen con A de 8 bits.
* X cambia antes de leer varios argumentos. No pases direcciones indexadas con X suponiendo que conservará el índice del sprite. Prefiere inmediatos o variables independientes de X para los datos de la transferencia.
* No incluyen <code>RTS</code> ni <code>RTL</code>. El código continúa después de la expansión. Comprueba el carry de las variantes normales antes de otra operación que lo modifique. Las variantes <code>Forced</code> no devuelven un indicador de éxito en carry.

Estas reglas también se aplican a las variantes <code>FromAddr</code>, <code>Resource</code> y <code>WithLenght</code>: preparan los argumentos y expanden la misma transferencia.

==== TransferToVRAM ====

<code>%TransferToVRAM()</code> programa una copia de gráficos desde ROM o RAM hacia VRAM.

<pre>
%TransferToVRAM(VRAMOffset, ResourceAddr, ResourceBNK, Lenght)
</pre>

* <code>VRAMOffset</code>: dirección de destino en VRAM, expresada en palabras de 2 bytes. Por ejemplo, copiar <code>$0200</code> bytes desde <code>$6000</code> ocupa las palabras <code>$6000-$60FF</code>.
* <code>ResourceAddr</code>: dirección de origen dentro de su banco.
* <code>ResourceBNK</code>: banco del origen.
* <code>Lenght</code>: cantidad de bytes que se copiarán. Se conserva esta escritura del nombre porque así aparece en la macro.

'''Ejemplo: programar la carga de gráficos'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToVRAM(#$6000, #!ResourceMyGraphics, #!ResourceMyGraphics>>16, #$0200)
BCC .NotLoaded
; La copia se realizará en el próximo NMI.
.NotLoaded
</pre>

<code>!ResourceMyGraphics</code> es la dirección de un recurso registrado desde un DynamicInfo; queda en <code>DXDefines.asm</code>. El nombre se normaliza eliminando espacios, guiones y guiones bajos y poniendo en mayúscula la inicial de cada palabra: <code>my_graphics</code> pasa a <code>MyGraphics</code>. La cantidad de bytes solicitada debe existir en ese recurso.

==== TransferToVRAMFromAddr ====

Hace la misma copia, pero recibe la dirección completa del origen. La macro separa su dirección y banco por ti.

<pre>
%TransferToVRAMFromAddr(VRAMOffset, addr, Lenght)
</pre>

<code>addr</code> se escribe sin <code>#</code>; los otros parámetros se entregan como en <code>TransferToVRAM</code>.

'''Ejemplo'''

<pre>
%TransferToVRAMFromAddr(#$6000, !ResourceMyGraphics, #$0200)
BCC .NotLoaded
.NotLoaded
</pre>

<code>!ResourceMyGraphics</code> se genera desde un recurso del DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase: <code>my_graphics</code> se convierte en <code>MyGraphics</code>.

==== TransferResourceToVRAM y TransferResourceToVRAMWithLenght ====

Estas variantes reciben el nombre de un recurso de Dynamic Xtreme. La primera copia el recurso completo; la segunda copia la cantidad de bytes que indiques.

<pre>
%TransferResourceToVRAM(VRAMOffset, ResourceName)
%TransferResourceToVRAMWithLenght(VRAMOffset, ResourceName, Lenght)
</pre>

Para un recurso cuyos defines sean <code>!ResourceMyGraphics</code> y <code>!ResourceMyGraphicsSize</code>, escribe <code>"MyGraphics"</code> como <code>ResourceName</code>.

'''Ejemplo: cargar el recurso completo'''

<pre>
%TransferResourceToVRAM(#$6000, "MyGraphics")
BCC .NotLoaded
.NotLoaded
</pre>

'''Ejemplo: cargar solo sus primeros $0200 bytes'''

<pre>
%TransferResourceToVRAMWithLenght(#$6000, "MyGraphics", #$0200)
BCC .NotLoaded
.NotLoaded
</pre>

El nombre y el tamaño se obtienen de los defines generados en <code>DXDefines.asm</code> al instalar los recursos del DynamicInfo. Utiliza el nombre normalizado: <code>my_graphics</code> pasa a <code>MyGraphics</code>, eliminando los separadores y poniendo en mayúscula la inicial de cada palabra.

==== TransferToCGRAM ====

<code>%TransferToCGRAM()</code> programa una copia de colores desde ROM o RAM hacia una paleta de SNES.

<pre>
%TransferToCGRAM(CGRAMOffset, TableAddr, TableBNK, Lenght)
</pre>

* <code>CGRAMOffset</code>: número del primer color de destino, entre <code>$00</code> y <code>$FF</code>. Por ejemplo, la paleta 8 comienza en el color <code>$80</code>.
* <code>TableAddr</code> y <code>TableBNK</code>: dirección y banco de los colores que se van a copiar.
* <code>Lenght</code>: cantidad de bytes. Cada color ocupa 2 bytes; 15 colores ocupan <code>$001E</code> bytes.

Los colores de origen deben estar en formato normal de SNES, BGR555. Si calculaste un efecto, utiliza su resultado final de 2 bytes por color, como el que producen las variantes <code>AndMerge</code>.

'''Ejemplo: copiar los 15 colores visibles de la paleta 8'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToCGRAM(#$81, #DX_PPU_CGRAM_PaletteWriteMirror+$0102, #DX_PPU_CGRAM_PaletteWriteMirror>>16, #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

Este ejemplo toma el resultado de un efecto guardado en <code>DX_PPU_CGRAM_PaletteWriteMirror</code>. El desplazamiento <code>$0102</code> corresponde al color <code>$81</code>, porque cada color ocupa 2 bytes. Se omite el primer color de la paleta, que es transparente en sprites.

==== TransferToCGRAMFromAddr ====

Hace la misma copia de colores, pero recibe la dirección completa del origen. Escribe <code>addr</code> sin <code>#</code>.

<pre>
%TransferToCGRAMFromAddr(CGRAMOffset, addr, Lenght)
</pre>

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToCGRAMFromAddr(#$81, DX_PPU_CGRAM_PaletteWriteMirror+$0102, #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

El resultado es el mismo que en el ejemplo anterior: programa la carga de 15 colores a partir del segundo color de la paleta 8.

==== TransferResourceToCGRAM y TransferResourceToCGRAMWithLenght ====

Estas variantes copian los colores de un recurso registrado en Dynamic Xtreme. La primera utiliza su tamaño completo; la segunda utiliza la cantidad de bytes que indiques.

<pre>
%TransferResourceToCGRAM(CGRAMOffset, ResourceName)
%TransferResourceToCGRAMWithLenght(CGRAMOffset, ResourceName, Lenght)
</pre>

'''Ejemplo: copiar un recurso completo de colores'''

<pre>
%TransferResourceToCGRAM(#$80, "MyColors")
BCC .NotLoaded
.NotLoaded
</pre>

'''Ejemplo: copiar solo 15 colores'''

<pre>
%TransferResourceToCGRAMWithLenght(#$81, "MyColors", #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

Estos ejemplos suponen un recurso general de colores con los defines <code>!ResourceMyColors</code> y <code>!ResourceMyColorsSize</code>, generados en <code>DXDefines.asm</code> desde un DynamicInfo. Utiliza el nombre normalizado: <code>my_colors</code> pasa a <code>MyColors</code>. En el segundo ejemplo, el recurso debe comenzar con los 15 colores que se quieren copiar, sin anteponer el color transparente.

==== Variantes Forced ====

Todas las transferencias anteriores tienen una variante cuyo nombre comienza con <code>Forced</code>. Programa la copia aunque supere el límite de bytes del frame. La cantidad copiada también se suma al total de ese frame.

{| class="wikitable"
! VRAM !! CGRAM
|-
| <code>ForcedTransferToVRAM</code> || <code>ForcedTransferToCGRAM</code>
|-
| <code>ForcedTransferToVRAMFromAddr</code> || <code>ForcedTransferToCGRAMFromAddr</code>
|-
| <code>ForcedTransferResourceToVRAM</code> || <code>ForcedTransferResourceToCGRAM</code>
|-
| <code>ForcedTransferResourceToVRAMWithLenght</code> || <code>ForcedTransferResourceToCGRAMWithLenght</code>
|}

Reciben los mismos parámetros que las versiones sin <code>Forced</code>. Su carry no indica si la transferencia fue aceptada. Prepara A en modo de 8 bits antes de utilizarlas; al terminar dejan A, X e Y en modo de 8 bits.

'''Ejemplo'''

<pre>
%ForcedTransferResourceToVRAM(#$6000, "MyGraphics")
; No se comprueba el carry en esta variante.
</pre>

<code>MyGraphics</code> corresponde al recurso <code>!ResourceMyGraphics</code> de <code>DXDefines.asm</code>, generado desde el DynamicInfo. Se utiliza el nombre normalizado, como <code>my_graphics</code> → <code>MyGraphics</code>.

Utiliza <code>Forced</code> para cargas que deben tener prioridad y cuyo tamaño ya controlas. Si fuerzas demasiados datos, las copias pueden superar el tiempo disponible para actualizar los gráficos. En las demás cargas, utiliza las variantes normales y comprueba el carry.

=== Matemáticas ===

Estas macros multiplican y dividen números utilizando el hardware de SNES o SA-1, según la ROM. Utilizan números sin signo: los valores representan cantidades positivas o cero.

Prepara A en modo de 8 bits antes de llamarlas. Las macros no cambian por ti el tamaño de A, X o Y.

'''Registros y memoria temporal:''' todas las macros de esta categoría, incluidas <code>W</code> y <code>After...</code>, modifican A y N/Z, conservan X, Y, carry, DBR y D, y no utilizan scratch. Mantienen el tamaño de los registros con el que entraron; A debe estar en 8 bits para que las escrituras al hardware sean correctas. DBR debe permitir acceder a los registros aritméticos de SNES o SA-1, según corresponda. No incluyen <code>RTS</code> ni <code>RTL</code>; el código continúa después de la macro. El resultado está en los registros hardware indicados abajo, no en A. El carry no informa de éxito ni de desbordamiento del cálculo.

'''Cómo escribir los argumentos'''

<code>Mul</code>, <code>Div</code>, <code>MulAfterMul</code> y <code>DivAfterDiv</code> pegan el argumento directamente después de <code>LDA</code>. Escribe el argumento entre comillas con un espacio al principio: <code>" #$05"</code> produce <code>LDA #$05</code>.

También puedes comenzar el argumento con <code>.b</code>, <code>.w</code> o <code>.l</code> para elegir cómo se escribe el acceso a memoria. Por ejemplo, si <code>$02</code> contiene el número que quieres multiplicar:

<pre>
%Mul(".b $02", " #$07")
</pre>

Esto genera <code>LDA.b $02</code> para leer el primer número y <code>LDA #$07</code> para el segundo. Los sufijos eligen cómo se accede a la dirección; no cambian cuántos bits tiene A. La multiplicación sigue utilizando números de 8 bits.

Las variantes con <code>W</code>, además de <code>MulAfterDiv</code> y <code>DivAfterMul</code>, ya añaden un espacio antes de los argumentos. En ellas puedes escribir los valores normalmente, como <code>%MulW(#$05, #$07)</code>. En la implementación actual no se pasan los sufijos <code>.b</code>, <code>.w</code> o <code>.l</code> de esta misma manera a esas variantes, porque el espacio que añaden quedaría entre <code>LDA</code> y el sufijo.

'''¿Qué significa la W?'''

El hardware necesita un pequeño tiempo para terminar el cálculo. Las macros con <code>W</code> incluyen esa espera: puedes leer el resultado inmediatamente después. Las versiones sin <code>W</code> permiten ejecutar otro código mientras se calcula, pero debes dejar pasar el tiempo necesario antes de leerlo. Si necesitas el resultado en la siguiente instrucción, utiliza la variante con <code>W</code>.

Los resultados se leen mediante estos defines:

* <code>!MultiplicationResult</code>: resultado de multiplicar, de 16 bits.
* <code>!DivisionResult</code>: cociente de la división, de 16 bits.
* <code>!RemainderResult</code>: resto de la división, de 16 bits.

Estos defines ya seleccionan la dirección correspondiente a SNES o SA-1. El siguiente cálculo puede cambiar los resultados anteriores; guárdalos si los necesitas después.

==== Mul y MulW ====

Multiplican dos valores de 8 bits y producen un resultado de 16 bits.

<pre>
%Mul(a, b)
%MulW(a, b)
</pre>

<code>a</code> y <code>b</code> pueden ser valores inmediatos, como <code>#$06</code>, o variables de 8 bits.

'''Ejemplo: 6 × 7 = 42'''

<pre>
%MulW(#$06, #$07)
REP #$20
LDA !MultiplicationResult ; A = $002A, es decir, 42
SEP #$20
</pre>

La llamada sin espera sería <code>%Mul(" #$06", " #$07")</code>. En ese caso no leas el resultado inmediatamente: ejecuta antes otro código que no utilice el hardware de multiplicación o división.

==== Div y DivW ====

Dividen un número de 16 bits por uno de 8 bits. El número de 16 bits se entrega separado en dos bytes: primero el alto y después el bajo.

<pre>
%Div(ah, al, b)
%DivW(ah, al, b)
</pre>

* <code>ah</code>: byte alto del número que quieres dividir.
* <code>al</code>: byte bajo del mismo número.
* <code>b</code>: número por el que divides, entre 1 y 255.

'''Ejemplo: 300 ÷ 7 = 42, con resto 6'''

<pre>
; 300 = $012C: byte alto $01, byte bajo $2C.
%DivW(#$01, #$2C, #$07)

REP #$20
LDA !DivisionResult ; A = $002A, es decir, 42
LDA !RemainderResult ; A = $0006
SEP #$20
</pre>

También puedes pasar una variable de 16 bits como dos argumentos: <code>%DivW(MiNumero+1, MiNumero, #$07)</code>. <code>MiNumero</code> representa aquí una variable definida por tu código.

==== Continuar desde el resultado anterior ====

Las variantes <code>AfterMul</code> y <code>AfterDiv</code> toman el resultado del cálculo anterior como primer número. Solo debes indicar el segundo número.

{| class="wikitable"
! Macro !! Cálculo que realiza
|-
| <code>MulAfterMul(b)</code> / <code>MulWAfterMul(b)</code> || Toma los 8 bits bajos del resultado de la multiplicación anterior y los multiplica por b.
|-
| <code>MulAfterDiv(b)</code> / <code>MulWAfterDiv(b)</code> || Toma los 8 bits bajos del cociente anterior y los multiplica por b.
|-
| <code>DivAfterMul(b)</code> / <code>DivWAfterMul(b)</code> || Divide el resultado completo de la multiplicación anterior por b.
|-
| <code>DivAfterDiv(b)</code> / <code>DivWAfterDiv(b)</code> || Divide el cociente completo de la división anterior por b.
|}

La W sigue indicando que puedes leer el nuevo resultado inmediatamente después. Las variantes <code>After...</code> ya incluyen la espera que necesitan para tomar el resultado del cálculo anterior.

'''Ejemplo: dos multiplicaciones, (6 × 7) × 2 = 84'''

<pre>
%Mul(" #$06", " #$07")
%MulWAfterMul(#$02)
REP #$20
LDA !MultiplicationResult ; A = $0054, es decir, 84
SEP #$20
</pre>

'''Ejemplo: dividir y después multiplicar, (100 ÷ 4) × 3 = 75'''

<pre>
%Div(" #$00", " #$64", " #$04")
%MulWAfterDiv(#$03)
REP #$20
LDA !MultiplicationResult ; A = $004B, es decir, 75
SEP #$20
</pre>

'''Ejemplo: multiplicar y después dividir, (20 × 15) ÷ 4 = 75'''

<pre>
%Mul(" #$14", " #$0F")
%DivWAfterMul(#$04)
REP #$20
LDA !DivisionResult ; A = $004B, es decir, 75
SEP #$20
</pre>

'''Ejemplo: dos divisiones, (300 ÷ 3) ÷ 4 = 25'''

<pre>
%Div(" #$01", " #$2C", " #$03")
%DivWAfterDiv(#$04)
REP #$20
LDA !DivisionResult ; A = $0019, es decir, 25
SEP #$20
</pre>

En las multiplicaciones, el primer número siempre se limita a 8 bits. Si el resultado anterior era mayor que 255, <code>MulAfterMul</code> o <code>MulAfterDiv</code> solo utilizará su byte bajo. Las divisiones de esta tabla sí toman el resultado anterior completo, de 16 bits.

es/Dynamic Xtreme ASM API

2026-10-25T17:23:56Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_ASM_API}}

En este artículo se explica cómo usar las rutinas y macros de Dynamic Xtreme desde código ASM. Cada entrada indica para qué sirve la llamada, qué datos debes preparar y qué obtienes al ejecutarla, junto con un ejemplo.

Para aprender a organizar un sprite completo, consulta la [[es/Dynamic_Xtreme_sprite_creation_guide|guía de creación de sprites]].

== Variables y defines ==

<code>DXDefines.asm</code> reúne los nombres que utiliza Dynamic Xtreme para acceder a sus variables, configuraciones, recursos y rutinas. Algunos representan datos que cambian durante el juego; otros son valores fijos o se generan al instalar los recursos.

Los nombres de variables generales comienzan con <code>DX_</code> y se escriben sin <code>!</code>, por ejemplo <code>DX_Timer</code>. Los defines como <code>!DynamicPoseIDMySprite000</code> sí llevan <code>!</code>. Conserva la escritura exacta del nombre que aparece en el archivo.

Las variables disponibles dependen de las funciones habilitadas durante la instalación. No es necesario memorizar todas: busca la categoría del sistema con el que estás trabajando.

=== Variables generales ===

En las tablas, el tamaño indica cuántos bytes ocupa un valor. Para una tabla se indica también cuántos valores contiene. Las variables marcadas como internas las actualiza Dynamic Xtreme; normalmente se utilizan las rutinas de la API para trabajar con ellas.

==== Contadores y cantidad de datos por frame ====

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Timer</code> || 2 bytes || Cuenta los frames en los que se ejecuta Dynamic Xtreme. Continúa durante la pausa y cuando se congela la acción. El sistema lo utiliza para saber cuándo se usó una pose por última vez.
|-
| <code>DX_SyncTimer</code> || 2 bytes || Cuenta los frames, pero se detiene cuando el juego está pausado o la acción está congelada. Puede utilizarse para animaciones que deban detenerse con el juego.
|-
| <code>DX_Dynamic_CurrentDataSend</code> || 2 bytes || Cantidad de bytes que ya se programaron para transferir durante el frame actual. La actualizan las rutinas de carga.
|-
| <code>DX_Dynamic_MaxDataPerFrame</code> || 2 bytes || Límite de bytes que las cargas normales pueden programar en un frame. Las variantes <code>Forced</code> pueden superarlo.
|}

==== Poses cargadas en VRAM ====

Estas tablas permiten al sistema saber qué poses están cargadas, dónde están y cuáles siguen en uso. Son datos internos de la caché; para solicitar una pose utiliza <code>!Upload</code> o <code>!TakeDynamicRequest</code>.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 byte || Cantidad de poses registradas actualmente en la caché.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 valores de 1 byte || Ayuda a encontrar las poses por su ID.
|-
| <code>DX_Dynamic_Pose_ID</code> || 128 valores de 2 bytes || ID de cada pose registrada.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 valores de 1 byte || Posición de los gráficos de cada pose en el espacio dinámico de VRAM, medida en bloques de 16×16.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 128 valores de 2 bytes || Valor de <code>DX_Timer</code> de la última vez que se utilizó cada pose. Evita reemplazar gráficos que todavía se están mostrando.
|-
| <code>DX_Dynamic_Tile_Size</code> / <code>DX_Dynamic_Tile_Pose</code> || 128 bytes compartidos || Describen las partes libres u ocupadas de VRAM. Son dos nombres para el mismo espacio de memoria.
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 valores de 1 byte || Ayuda al sistema a recorrer las partes libres y ocupadas de VRAM.
|}

==== Paletas y efecto global ====

Las tablas de 16 paletas utilizan el orden 0-F. En las tablas de valores de 2 bytes, la paleta 1 comienza en <code>+2</code>, la 2 en <code>+4</code>, y así sucesivamente.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 byte || Cada bit indica si una de las paletas 0-7 recibe el efecto global.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 byte || Cada bit indica si una de las paletas de sprites 8-F recibe el efecto global.
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 bytes || ID del efecto global que se quiere aplicar. El valor 0 indica que no se aplica un efecto global.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectID</code> || 2 bytes || Último efecto global revisado por el sistema. Se utiliza para detectar cambios.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 16 valores de 2 bytes || Último efecto global calculado para cada paleta. <code>$FFFF</code> significa que aún no hay un resultado; <code>$FFFE</code>, que hay una actualización pendiente y se conserva el resultado anterior.
|-
| <code>DX_Dynamic_Palettes_ID</code> || 16 valores de 2 bytes || ID asociado a cada paleta. <code>$FFFF</code> indica que está libre; <code>$FFFE</code> la excluye de la selección automática.
|-
| <code>DX_Dynamic_Palettes_Updated</code> || 16 valores de 1 byte || Indica cuáles paletas ya se actualizaron durante el frame. Uso interno.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 valores de 1 byte || Mientras sea distinto de 0, protege la paleta para que no sea reemplazada por otra asignación automática. Las llamadas que la utilizan vuelven a ponerlo en 2.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 byte || Registra qué paletas de sprites se utilizan con efectos. Uso interno del manejo de paletas.
|}

Para reservar una paleta de sprites y evitar que la selección automática la utilice, su entrada de <code>DX_Dynamic_Palettes_ID</code> debe contener <code>$FFFE</code>. Haz la reserva antes de que los sprites comiencen a solicitar paletas.

==== Copias de colores y resultados de efectos ====

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 bytes || Copia de trabajo de las 256 entradas de color, con 2 bytes por color. Es la fuente de las variantes <code>SetRGBBaseDefault</code> y <code>SetHSLBaseDefault</code>.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 bytes || Colores originales separados en rojo, verde y azul: 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 bytes || Colores originales separados en tono, saturación y luminosidad: 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_LocalEffectBuffer</code> || 768 bytes || Espacio de trabajo para el resultado de un efecto local antes de combinarlo con el global.
|-
| <code>DX_PPU_CGRAM_LocalEffectID</code> || 16 valores de 2 bytes || ID del efecto local aplicado a cada paleta.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 bytes || Colores resultantes en formato de SNES, con 2 bytes por color. Las variantes <code>AndMergeDefault</code> escriben aquí.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> / <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 byte cada una || Cada bit indica si ya se preparó la base RGB de una paleta de fondo o de sprites.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> / <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 byte cada una || Lo mismo para las bases HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> / <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 byte cada una || Cada bit indica si ya hay un resultado del efecto para esa paleta.
|-
| <code>DX_PPU_CGRAM_LastPlayerPal</code> || 2 bytes || Dirección de la última paleta del jugador procesada. El sistema la compara para detectar cambios.
|}

Escribir colores en una copia de RAM no los envía inmediatamente a CGRAM. Utiliza las rutinas de paleta o una transferencia para actualizar lo que se muestra en pantalla. Los indicadores de bases y efectos preparados los administra el sistema; no es necesario borrarlos antes de cada llamada.

==== Color fijo y primer color de la paleta ====

El color fijo es el color que SNES puede utilizar para efectos como sumas y restas de color. El color 0,0 es la primera entrada de CGRAM. Dynamic Xtreme permite aplicar el efecto global a ambos por separado.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 byte || Activa la participación en el efecto global: bit <code>$01</code> para el color fijo y bit <code>$02</code> para el color 0,0. <code>$03</code> permite ambos.
|-
| <code>DX_PPU_ColorEffect_BaseLoaded</code> || 1 byte || Indica si se guardaron sus colores originales. Utiliza un bit por destino: <code>$01</code> y <code>$02</code>.
|-
| <code>DX_PPU_ColorEffect_RGBBaseLoaded</code> / <code>DX_PPU_ColorEffect_HSLBaseLoaded</code> || 1 byte cada una || Indican si sus colores ya se prepararon en RGB o HSL, con los mismos bits.
|-
| <code>DX_PPU_FixedColor_Mirror</code> || 2 bytes || Copia del color fijo que utiliza la actualización habitual del juego.
|-
| <code>DX_PPU_FixedColor_Base</code> || 2 bytes || Color fijo original, antes de los efectos.
|-
| <code>DX_PPU_FixedColor_RGBBase</code> / <code>DX_PPU_FixedColor_HSLBase</code> || 3 bytes cada una || Color fijo original separado en RGB o HSL.
|-
| <code>DX_PPU_FixedColor_Result</code> || 2 bytes || Color fijo calculado después del efecto.
|-
| <code>DX_PPU_FixedColor_LastGlobalEffectID</code> || 2 bytes || Último efecto global calculado para el color fijo.
|-
| <code>DX_PPU_PaletteColor00_Base</code> || 2 bytes || Color 0,0 original.
|-
| <code>DX_PPU_PaletteColor00_RGBBase</code> / <code>DX_PPU_PaletteColor00_HSLBase</code> || 3 bytes cada una || Color 0,0 original separado en RGB o HSL.
|-
| <code>DX_PPU_PaletteColor00_Result</code> || 2 bytes || Color 0,0 que se quiere mostrar.
|-
| <code>DX_PPU_PaletteColor00_LastGlobalEffectID</code> || 2 bytes || Último efecto global calculado para el color 0,0.
|-
| <code>DX_PPU_PaletteColor00_Update</code> || 1 byte || Un valor distinto de 0 solicita copiar <code>Result</code> al color 0,0 durante NMI. Después de copiarlo, el sistema vuelve a poner esta variable en 0.
|}

==== Transferencias pendientes ====

Estas variables guardan las copias que se realizarán durante NMI. Las macros de la sección PPU las rellenan por ti. Cada copia necesita un origen, un destino y una cantidad de bytes.

{| class="wikitable"
! Variable !! Contenido
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || Cantidad de copias de gráficos pendientes, en 1 byte.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || Cantidad de bytes de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || Destino de cada copia en VRAM, en valores de 2 bytes.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || Dirección de origen de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || Banco de origen de cada copia. La tabla reserva 2 bytes por entrada.
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || Cantidad de copias de colores pendientes, en 1 byte.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || Cantidad de bytes de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || Primer color de destino de cada copia, en valores de 1 byte.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || Dirección de origen de cada copia, en valores de 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || Banco de origen de cada copia.
|}

==== Jugador y Yoshi ====

Estas variables permiten cambiar de dónde se obtienen los gráficos y colores del jugador y los gráficos de Yoshi. Los archivos gráficos deben conservar la organización que esperan las rutinas del juego.

{| class="wikitable"
! Variable !! Tamaño !! Para qué sirve
|-
| <code>DX_Dynamic_Player_GFX_Enable</code> || 1 byte || 0 desactiva la carga de gráficos mediante este sistema; un valor distinto de 0 la activa.
|-
| <code>DX_Dynamic_Player_GFX_Addr</code> || 2 bytes || Dirección de inicio de los gráficos del jugador dentro del banco indicado.
|-
| <code>DX_Dynamic_Player_GFX_BNK</code> || 2 bytes reservados || Banco de origen de los gráficos del jugador. El banco se indica en el byte bajo.
|-
| <code>DX_Dynamic_Player_Palette_Enable</code> || 1 byte || 0 desactiva el manejo de paleta del jugador mediante este sistema; un valor distinto de 0 lo activa.
|-
| <code>DX_Dynamic_Player_Palette_Addr</code> || 2 bytes || Dirección de origen de la paleta del jugador.
|-
| <code>DX_Dynamic_Player_Palette_BNK</code> || 1 byte || Banco de la paleta. Cuando es 0, la rutina toma la dirección de paleta que utiliza el juego.
|-
| <code>DX_Dynamic_Player_CustomPlayer</code> / <code>DX_Dynamic_Player_LastCustomPlayer</code> || 1 byte cada una || Variables reservadas para identificar al jugador personalizado y el anterior. La inicialización las pone en 0 y <code>$FF</code>; actualmente no seleccionan por sí solas los gráficos de un personaje.
|-
| <code>DX_Dynamic_Yoshi_VRAMEnable</code> || 1 byte || 0 desactiva la carga de gráficos de Yoshi mediante este sistema; un valor distinto de 0 la activa.
|-
| <code>DX_Dynamic_Yoshi_Addr</code> || 2 bytes || Dirección de inicio de los gráficos de Yoshi dentro de su banco.
|-
| <code>DX_Dynamic_Yoshi_BNK</code> || 1 byte || Banco de origen de los gráficos de Yoshi.
|}

==== Dibujo y variables de sprites ====

<code>DX_Drawing_InitialIndexHighPriority</code> y <code>DX_Drawing_InitialIndexLowPriority</code> ocupan 1 byte cada una y llevan la cuenta de las posiciones disponibles para dibujar sprites de prioridad alta o baja. <code>DX_Drawing_OAMMap</code> ocupa 128 bytes y ayuda a organizar los tiles dibujados. Estas variables se utilizan en la versión LoROM; el dibujo en SA-1 utiliza su manejo correspondiente.

Las variables individuales de sprites se definen en <code>DynamicXSpritesTables.asm</code>. Los archivos <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code> y <code>ExtendedSpriteDefines.asm</code> permiten utilizar los mismos nombres para los tres tipos:

{| class="wikitable"
! Nombre para el sprite !! Qué guarda
|-
| <code>!PoseIndex,x</code> || Pose que se quiere mostrar.
|-
| <code>!LastPoseIndex,x</code> || Última pose que se consiguió y puede dibujarse. Se inicia en <code>$FF</code>.
|-
| <code>!LastPoseHashIndex,x</code> || Entrada donde el sistema tiene registrada la ubicación de sus gráficos. Se inicia en <code>$FF</code>.
|-
| <code>!GlobalFlip,x</code> / <code>!LocalFlip,x</code> / <code>!LastFlip,x</code> || Volteo general, volteo adicional de la pose y volteo que se utiliza para dibujar.
|-
| <code>!Palette,x</code> || Paleta asignada: <code>$00</code> para la 8, <code>$02</code> para la 9, y así hasta <code>$0E</code> para la F. Se inicia en <code>$FF</code> cuando se utiliza asignación dinámica.
|-
| <code>!PaletteOption,x</code> || Opciones <code>EPPP----</code>: efecto global y elección de paleta o grupo de paletas.
|-
| <code>!PaletteAssignmentOption,x</code> || Modo de asignación: automático, manual o manual sin cargar colores.
|-
| <code>!Version,x</code> / <code>!LastVersion,x</code> || Variante del sprite y última variante procesada al manejar su paleta. <code>!LastVersion</code> se inicia en <code>$FF</code>.
|-
| <code>!RenderXDistanceOutOfScreen,x</code> / <code>!RenderYDistanceOutOfScreen,x</code> || Distancias que permiten seguir dibujando el sprite cuando su posición está fuera de la pantalla, pero alguna parte de su pose todavía puede verse.
|-
| <code>!SafeFrameLowByte,x</code> / <code>!SafeFrameHighByte,x</code> || Último frame en que se intentó solicitar una pose, para evitar repetir el trabajo durante el mismo frame.
|-
| <code>!AnimationIndex,x</code> / <code>!AnimationPoseIndex,x</code> / <code>!AnimationTimer,x</code> || Variables disponibles para llevar la cuenta de la animación, su paso actual y su temporizador. El código del recurso decide cómo utilizarlas.
|-
| <code>!State,x</code> || Variable para el estado o comportamiento del recurso.
|}

Cada variable de esta tabla ocupa 1 byte por sprite. Hay <code>!MaxSprites</code> entradas para normales, 20 para cluster y 10 para extended. No utilices <code>!MaxSprites</code> como cantidad de entradas de cluster o extended.

<code>DX_FreeRams</code> y <code>DX_FreeRams2</code> marcan el comienzo de las áreas donde se colocan estas tablas. No representan memoria libre para guardar datos propios encima de las variables de sprites.

=== Defines fijos ===

Estos nombres representan configuraciones y direcciones conocidas. No son variables que cambian durante el juego.

==== Compatibilidad con LoROM y SA-1 ====

<code>DXDefines.asm</code> detecta el tipo de ROM y elige los valores correspondientes. Utiliza estos nombres para que tu código funcione en ambos casos.

{| class="wikitable"
! Define !! LoROM !! SA-1 !! Uso
|-
| <code>!sa1</code> || 0 || 1 || Permite elegir código distinto según el tipo de ROM.
|-
| <code>!dp</code> || <code>$0000</code> || <code>$3000</code> || Ajuste de las direcciones de página directa.
|-
| <code>!addr</code> || <code>$0000</code> || <code>$6000</code> || Ajuste de las direcciones RAM que lo requieren, por ejemplo <code>$0100|!addr</code>.
|-
| <code>!rom</code> || <code>$800000</code> || <code>$000000</code> || Ajuste utilizado al acceder a direcciones del código original del juego.
|-
| <code>!MaxSprites</code> || <code>$0C</code> (12) || <code>$16</code> (22) || Cantidad de posiciones de sprites normales.
|-
| <code>!MultiplicationResult</code> || <code>$4216</code> || <code>$2306</code> || Dirección donde se lee el resultado de una multiplicación.
|-
| <code>!DivisionResult</code> || <code>$4214</code> || <code>$2306</code> || Dirección donde se lee el cociente de una división.
|-
| <code>!RemainderResult</code> || <code>$4216</code> || <code>$2308</code> || Dirección donde se lee el resto de una división.
|}

Otros defines utilizados para colocar las variables son <code>!normalBnk</code>, <code>!PalCopyBNK</code>, <code>!Variables</code> y <code>!Variables2</code>. Normalmente basta con utilizar el nombre de cada variable <code>DX_...</code>, sin calcular su dirección a partir de estos valores.

==== Direcciones de gráficos en VRAM ====

Estos defines permiten indicar el destino de una transferencia sin escribir su dirección numérica. Cada familia tiene líneas de 0 a 7; sustituye N por el número de línea.

{| class="wikitable"
! Familia !! Línea 0 !! Avance por línea !! Ejemplo
|-
| <code>!FG1LineN</code> || <code>$0000</code> || <code>$0100</code> || <code>!FG1Line1 = $0100</code>
|-
| <code>!FG2LineN</code> || <code>$0800</code> || <code>$0100</code> || <code>!FG2Line1 = $0900</code>
|-
| <code>!BG1LineN</code> || <code>$1000</code> || <code>$0100</code> || <code>!BG1Line1 = $1100</code>
|-
| <code>!FG3LineN</code> || <code>$1800</code> || <code>$0100</code> || <code>!FG3Line1 = $1900</code>
|-
| <code>!BG2LineN</code> || <code>$2000</code> || <code>$0100</code> || <code>!BG2Line1 = $2100</code>
|-
| <code>!BG3LineN</code> || <code>$2800</code> || <code>$0100</code> || <code>!BG3Line1 = $2900</code>
|-
| <code>!LG1LineN</code> a <code>!LG4LineN</code> || <code>$4000</code>, <code>$4400</code>, <code>$4800</code>, <code>$4C00</code> || <code>$0080</code> || <code>!LG1Line1 = $4080</code>
|-
| <code>!SP1LineN</code> a <code>!SP4LineN</code> || <code>$6000</code>, <code>$6800</code>, <code>$7000</code>, <code>$7800</code> || <code>$0100</code> || <code>!SP4Line1 = $7900</code>
|}

<code>!Layer1Tilemap = $3000</code> y <code>!Layer2Tilemap = $3800</code> indican las direcciones habituales de los mapas de tiles de Layer 1 y Layer 2. Las direcciones de VRAM de esta sección se expresan en palabras de 2 bytes, como las que reciben las macros de transferencia.

==== Configuraciones de espacio para poses dinámicas ====

Los defines <code>!DynamicSpaceConfig...</code> se entregan a <code>!DynamicPoseSpaceConfig</code>. El nombre indica qué áreas de gráficos se permiten utilizar. <code>FirstHalf</code> significa primera mitad y <code>SecondHalf</code>, segunda mitad. Los nombres con <code>WithPlayer</code> o <code>WithDSX</code> corresponden a las configuraciones previstas para esos casos.

{| class="wikitable"
! Valor !! Define
|-
| <code>$00</code> || <code>!DynamicSpaceConfigSecondHalfSSP4</code>
|-
| <code>$01</code> || <code>!DynamicSpaceConfigSP4</code>
|-
| <code>$02</code> || <code>!DynamicSpaceConfigSecondHalfSP3</code>
|-
| <code>$03</code> || <code>!DynamicSpaceConfigFirstHalfSP3</code>
|-
| <code>$04</code> || <code>!DynamicSpaceConfigSP3</code>
|-
| <code>$05</code> || <code>!DynamicSpaceConfigSecondHalfSP2</code>
|-
| <code>$06</code> || <code>!DynamicSpaceConfigFirstHalfSP2</code>
|-
| <code>$07</code> || <code>!DynamicSpaceConfigSP2</code>
|-
| <code>$08</code> || <code>!DynamicSpaceConfigSecondHalfSP1</code>
|-
| <code>$09</code> || <code>!DynamicSpaceConfigFirstHalfSP1</code>
|-
| <code>$0A</code> || <code>!DynamicSpaceConfigSP1</code>
|-
| <code>$0B</code> || <code>!DynamicSpaceConfigFirstHalfSP1WithPlayer</code>
|-
| <code>$0C</code> || <code>!DynamicSpaceConfigSP11WithPlayer</code>
|-
| <code>$0D</code> || <code>!DynamicSpaceConfigSecondHalfSP3ndSP4</code>
|-
| <code>$0E</code> || <code>!DynamicSpaceConfigSP34</code>
|-
| <code>$0F</code> || <code>!DynamicSpaceConfigSecondHalfSP2andSP34</code>
|-
| <code>$10</code> || <code>!DynamicSpaceConfigSP234</code>
|-
| <code>$11</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234</code>
|-
| <code>$12</code> || <code>!DynamicSpaceConfigSP1234</code>
|-
| <code>$13</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithPlayer</code>
|-
| <code>$14</code> || <code>!DynamicSpaceConfigSP1234WithPlayer</code>
|-
| <code>$15</code> || <code>!DynamicSpaceConfigSecondHalfSP3ndSP4WithDSX</code>
|-
| <code>$16</code> || <code>!DynamicSpaceConfigSP34WithDSX</code>
|-
| <code>$17</code> || <code>!DynamicSpaceConfigSecondHalfSP2andSP34WithDSX</code>
|-
| <code>$18</code> || <code>!DynamicSpaceConfigSP234WithDSX</code>
|-
| <code>$19</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithDSX</code>
|-
| <code>$1A</code> || <code>!DynamicSpaceConfigSP1234WithDSX</code>
|-
| <code>$1B</code> || <code>!DynamicSpaceConfigSecondHalfSP1andSP234WithPlayerAndDSX</code>
|-
| <code>$1C</code> || <code>!DynamicSpaceConfigSP1234WithPlayerAndDSX</code>
|}

Los nombres de esta tabla se escriben exactamente como aparecen en <code>DXDefines.asm</code>, incluidos nombres como <code>SecondHalfSSP4</code> y <code>SP11WithPlayer</code>.

==== Otras constantes ====

{| class="wikitable"
! Define !! Valor o uso
|-
| <code>!AN2Buffer1</code> / <code>!AN2Buffer2</code> || Direcciones <code>$7EC100</code> y <code>$7EAD00</code> utilizadas para datos de animación.
|-
| <code>!GFX32Buffer</code> || <code>$7E2000</code>, dirección del buffer habitual de GFX32.
|-
| <code>!PlayerPaletteColor2To5</code> || <code>$00B280</code>, datos de los colores 2-5 de la paleta del jugador.
|-
| <code>!PlayerBasePalette</code> || <code>$00B2C8</code>, datos de la paleta base del jugador.
|-
| <code>!VRAMTransferSize</code> / <code>!CGRAMTransferSize</code> || Ambos valen 64 en la plantilla actual. Se utilizan para reservar las tablas de transferencias; no representan el límite de bytes que se cargan por frame.
|}

Las opciones de instalación, como <code>!DynamicPoses</code>, <code>!DrawingSystem</code>, <code>!GraphicsChange</code>, <code>!PalettesChange</code>, <code>!PalettesEffects</code>, <code>!PlayerFeatures</code> y <code>!YoshiFeatures</code>, se incluyen desde <code>Options.asm</code>. Sus valores indican qué funciones se instalaron; no se cambian durante el juego.

=== Defines generados ===

Dynamic Xtreme crea estos defines al instalar los recursos y los añade a <code>DXDefines.asm</code>. Utiliza sus nombres en lugar de copiar los valores numéricos, porque los IDs, direcciones y tamaños pueden cambiar cuando se agregan o modifican recursos.

Los nombres se normalizan en PascalCase: se eliminan espacios, guiones bajos, guiones y otros separadores, y se pone en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_sprite</code>, <code>my-sprite</code> y <code>my sprite</code> se convierten en <code>MySprite</code>. Se conserva el resto de las mayúsculas y minúsculas que ya tenía el nombre. Ante una duda, copia el nombre exacto de <code>DXDefines.asm</code>.

==== Poses dinámicas y poses de dibujo ====

{| class="wikitable"
! Familia o ejemplo !! Qué representa
|-
| <code>!DynamicPoseIDMySprite000</code> || ID de unos gráficos de pose declarados en el DynamicInfo. Se utiliza para solicitar su carga con <code>!Upload</code>.
|-
| <code>!DynamicPoseMySprite000</code> || Dirección ROM de esos gráficos.
|-
| <code>!DynamicPoseMySprite000Size</code> || Tamaño de esos gráficos en bytes.
|-
| <code>!PoseIDMySprite_Frame0</code> || ID de una pose del DrawInfo. Se utiliza para dibujarla con <code>!DXDraw</code> o <code>DrawStatic</code>.
|-
| <code>!RenderBoxXDistanceOutOfScreenMySprite</code> || Distancia horizontal calculada desde el DrawInfo para saber cuándo el sprite deja de verse.
|-
| <code>!RenderBoxYDistanceOutOfScreenMySprite</code> || Distancia vertical calculada desde el DrawInfo para la misma comprobación.
|}

El ID dinámico elige qué gráficos cargar; el ID de dibujo elige cómo colocar los tiles para formar la pose. Son valores distintos. Un define <code>!DynamicPoseID...</code> no se utiliza en lugar de un <code>!PoseID...</code>.

==== Paletas y efectos ====

{| class="wikitable"
! Familia o ejemplo !! Qué representa
|-
| <code>!PaletteIDMyPalette</code> || ID de una paleta declarada desde el DynamicInfo.
|-
| <code>!PaletteMyPalette</code> || Dirección ROM de sus colores.
|-
| <code>!PaletteMyPaletteSize</code> || Tamaño de la paleta en bytes.
|-
| <code>!MySpritePaletteTableOffset</code> || Indica dónde comienza la lista de paletas de ese DynamicInfo. Se entrega a <code>!PaletteAssignment</code> y a sus variantes.
|-
| <code>!PaletteEffectIDMyEffect0</code> || ID de un efecto de <code>my_effect.paleffect</code>. El número final identifica el efecto dentro del archivo; los IDs globales comienzan en 1.
|-
| <code>!PaletteMyTargetRGB</code> / <code>!PaletteMyTargetHSL</code> || Dirección ROM de una paleta de destino convertida para una transición RGB o HSL. Se genera cuando un efecto necesita esa paleta.
|-
| <code>!PaletteMyTargetRGBSize</code> / <code>!PaletteMyTargetHSLSize</code> || Tamaño en bytes de esas paletas convertidas.
|}

Los nombres de los ejemplos usan la misma normalización: <code>my_palette</code> pasa a <code>MyPalette</code> y <code>my_effect</code> a <code>MyEffect</code>. Los defines se generan durante la instalación y quedan en <code>DXDefines.asm</code>.

==== Recursos generales y buffers ====

{| class="wikitable"
! Familia o ejemplo !! Qué representa
|-
| <code>!ResourceIDMyResource</code> || ID de un recurso general del DynamicInfo.
|-
| <code>!ResourceMyResource</code> || Dirección ROM de ese recurso.
|-
| <code>!ResourceMyResourceSize</code> || Tamaño del recurso en bytes.
|-
| <code>!BufferIDMyBuffer</code> || ID de un buffer insertado por la herramienta.
|-
| <code>!BufferMyBuffer</code> || Dirección del buffer insertado en la ROM; no es una variable temporal de RAM.
|-
| <code>!BufferMyBufferSize</code> || Tamaño del buffer en bytes.
|}

Los nombres dependen de los recursos instalados. Se normalizan del mismo modo: <code>my_resource</code> pasa a <code>MyResource</code>. Consulta <code>DXDefines.asm</code> para ver los nombres y valores de tu instalación.

==== Cantidades y tablas generadas ====

Estos defines permiten consultar las cantidades y las tablas creadas al instalar los recursos. Para un sprite normal suele bastar con utilizar los IDs individuales de las tablas anteriores.

{| class="wikitable"
! Define !! Qué representa
|-
| <code>!NumberOfDynamicPoses</code> / <code>!NumberOfPoses</code> || Cantidad de poses dinámicas y de poses de dibujo instaladas, respectivamente.
|-
| <code>!NumberOfPalettes</code> / <code>!NumberOfResources</code> / <code>!NumberOfBuffers</code> || Cantidad de paletas normales, recursos generales y buffers insertados.
|-
| <code>!NumberOfPaletteEffects</code> || Valor usado para dimensionar las tablas de efectos. La generación incluye el espacio del ID 0; no lo interpretes como cantidad de efectos escritos en un archivo <code>*.paleffect</code>.
|-
| <code>!PaletteTableSize</code> || Cantidad total de entradas en las listas de paletas de los DynamicInfo.
|-
| <code>!PaletteIDTables</code> || Dirección de la tabla de IDs de esas listas de paletas.
|-
| <code>!PaletteAddrTables</code> || Dirección de la tabla con las direcciones ROM de sus colores.
|-
| <code>!PaletteEffectsTypes</code> || Tabla con el tipo de cada efecto instalado.
|-
| <code>!PaletteEffectsChannels1</code>, <code>!PaletteEffectsChannels2</code>, <code>!PaletteEffectsChannels3</code> || Tablas con los valores de color de cada efecto.
|-
| <code>!PaletteEffectsRatios1</code>, <code>!PaletteEffectsRatios2</code>, <code>!PaletteEffectsRatios3</code> || Tablas con los ratios que controlan cuánto se aplica cada cambio.
|-
| <code>!BufferTable</code>, <code>!PaletteTables</code>, <code>!PaletteEffectsTable</code> || Direcciones de las tablas que el parche publica para esos datos.
|}

=== Defines de rutinas ===

Estos defines representan llamadas del sistema, no variables para guardar datos. La tabla sirve para encontrarlas; su uso se explica en las secciones de rutinas y macros.

{| class="wikitable"
! Define o familia !! Uso
|-
| <code>!AllowedGameMode</code> || Comprueba si el modo de juego actual permite procesar las operaciones correspondientes.
|-
| <code>!DynamicPoseSpaceConfig</code> || Elige las partes de VRAM disponibles para poses dinámicas.
|-
| <code>!TakeDynamicRequest</code> || Solicita una pose por su ID.
|-
| <code>!DynamicRoutine</code> || Prepara las copias de gráficos de una pose a VRAM.
|-
| <code>!SetPropertyAndOffset</code> || Obtiene la ubicación y propiedades de los gráficos de una pose dinámica para dibujarla.
|-
| <code>!Draw</code> / <code>!Draw_Return</code> || Entrada y punto de retorno utilizados por las rutinas de dibujo.
|-
| <code>!RemapOamTile</code> || Ajusta el número de tile para utilizar la ubicación real de los gráficos dinámicos.
|-
| <code>!IsValid</code>, <code>!XIsValid</code>, <code>!YIsValid</code> || Comprobaciones utilizadas por el dibujo para decidir si un tile puede mostrarse.
|-
| <code>!AssignPalette</code> || Selecciona el destino de una paleta según el modo de asignación.
|-
| <code>!LoadPaletteOnBuffer</code> || Carga datos de paleta en un espacio de trabajo para procesarlos.
|-
| <code>!SetRGBBase</code> / <code>!SetHSLBase</code> || Prepara los colores para calcular efectos RGB o HSL.
|-
| <code>!RGBToHSL</code> / <code>!HSLToRGB</code> || Convierte entre ambos sistemas de color.
|-
| <code>!RGBMerge</code> || Convierte colores RGB separados al formato de paleta de SNES.
|-
| <code>!Mix...</code> / <code>!MixAndMerge...</code> || Aplica cambios a uno o varios componentes del color.
|-
| <code>!PalTransitionRGB</code> / <code>!PalTransitionHSL</code> || Calcula el cambio de una paleta a otra.
|-
| <code>!PalTransitionAndMergeRGB</code> / <code>!PalTransitionAndMergeHSL</code> || Calcula la transición y deja el resultado en formato de SNES.
|-
| <code>!DoEffect</code> / <code>!DoEffectAndMerge</code> || Aplica un efecto mediante su ID.
|-
| <code>!PalFunctionRGB</code>, <code>!PalFunctionHSL</code> y variantes <code>AndMerge</code> || Nombres reservados para funciones de color que todavía no están implementadas.
|}

<code>!Routines</code> es la dirección de la tabla desde la que se obtienen estas llamadas. No necesitas calcular sus posiciones para usar los defines publicados.

== Estado del CPU y memoria temporal ==

Cada llamada necesita que los registros tengan el tamaño indicado en su entrada. Un registro puede terminar en 8 bits y aun así haber perdido su valor anterior: '''tamaño y contenido son cosas distintas'''.

Estas reglas se aplican a las llamadas de este artículo, salvo las excepciones indicadas en cada entrada:

* Ejecuta el código en modo nativo, con el modo decimal desactivado. Las operaciones matemáticas del sistema utilizan números binarios.
* '''Direct page D:''' <code>$0000</code> en LoROM y <code>$3000</code> en el contexto habitual de SA-1 Pack. Las direcciones cortas como <code>$00</code> se interpretan respecto de esa base. Las llamadas no preparan ni cambian D por ti.
* '''Banco de datos DBR:''' debe permitir acceder a los espejos de RAM y a los registros hardware utilizados por la llamada. El contexto habitual usa bancos con esos espejos, como <code>$00-$3F</code> o <code>$80-$BF</code>. Si entregas un operando que lee una tabla mediante una dirección de 16 bits, DBR también debe permitir leer esa tabla. Un puntero de 24 bits lleva su propio banco. <code>DynamicRoutine</code> tiene un requisito específico de DBR, explicado en su entrada.
* Las llamadas conservan DBR y D. Algunas cambian DBR temporalmente y lo restauran antes de retornar. Esto no significa que cualquier banco de entrada sea válido.
* '''Flags:''' utiliza como resultado únicamente los que se indiquen expresamente. No supongas que N, Z, V o carry conservan su valor anterior. Los cambios de tamaño de A y X/Y se indican por llamada.
* '''Memoria temporal:''' las scratch indicadas pueden sobrescribirse tanto en éxito como en fallo. Guarda fuera de ellas cualquier dato que necesites después. Las salidas solo son válidas en las condiciones descritas en cada entrada.
* '''Pila:''' las llamadas retiran los datos temporales que ellas mismas apilan. Tu código debe emparejar sus propios pushes y pulls con el mismo tamaño de registro, y respetar el retorno de la rutina o macro.

Para conservar un registro, guárdalo antes de la llamada y recupéralo después con el mismo tamaño. Si necesitas comprobar el carry devuelto, hazlo antes de ejecutar otra operación que lo modifique; restaurar P mediante <code>PLP</code> también reemplaza ese carry.

== Rutinas para sprites ==

Estas rutinas permiten comprobar si un sprite debe dibujarse en pantalla, cargar sus gráficos y manejar sus paletas. Antes de utilizarlas, incluye el archivo de defines correspondiente: <code>NormalSpriteDefines.asm</code>, <code>ClusterSpriteDefines.asm</code> o <code>ExtendedSpriteDefines.asm</code>. La ruta del include es relativa al archivo ASM del sprite.

Los requisitos de DBR, D, flags y pila se explican en [[#Estado del CPU y memoria temporal|Estado del CPU y memoria temporal]]. La tabla siguiente distingue el tamaño de los registros de los valores que conservan.

Para usar llamadas como <code>!RenderBox</code> o <code>!Upload</code>, escribe su nombre directamente, como muestran los ejemplos. No añadas <code>JSR</code> ni <code>JSL</code> delante. Salvo que se indique lo contrario, X debe contener el número del slot que ocupa el sprite.

'''Registros y scratch de las llamadas para sprites'''

Entra con X e Y en modo de 8 bits. El tamaño de A depende de la llamada:

{| class="wikitable"
! Llamada !! A al entrar !! Registros al volver !! Scratch que puede sobrescribir
|-
| <code>!RenderBox</code>
| 8 bits.
| A cambia y queda en 8 bits. X e Y conservan su valor y tamaño.
| No utiliza scratch; modifica las tablas de Dynamic Xtreme descritas en su entrada.
|-
| <code>!PaletteAssignment</code> y <code>!PaletteAssignmentNoUpload</code>
| 16 bits con <code>PalettesChange</code> habilitado; 8 bits si está deshabilitado, sin utilizar el offset de tabla.
| A e Y pueden cambiar. X vuelve a cargarse desde <code>!SpriteIndex</code> cuando se utiliza para el trabajo interno. La variante sin carga devuelve información en Y. Los tres quedan en 8 bits.
| <code>$00-$0F</code>, <code>$65-$67</code>, <code>$D5</code>, según el camino utilizado. Con efectos, también puede utilizar los temporales de efectos indicados más abajo.
|-
| <code>!Upload</code> y <code>!UploadWithoutPoseOffset</code>
| 16 bits.
| A e Y pueden cambiar. X se recupera desde <code>!SpriteIndex</code>. Los tres quedan en 8 bits.
| <code>$00-$0F</code> y <code>$47-$51</code> cuando necesita preparar una carga nueva.
|-
| <code>!DXDraw</code> y <code>!DXDrawWithOffset</code>
| 16 bits.
| A e Y pueden cambiar. Si dibuja, X se recupera desde <code>!SpriteIndex</code>; si no hay pose válida, conserva el X de entrada. Los tres quedan en 8 bits.
| <code>$00-$0F</code>, <code>$45-$4F</code> y <code>$8A</code>. Con desplazamiento adicional, también <code>$8B-$8C</code>.
|-
| <code>!ReplacePalette</code>
| 8 bits.
| A e Y pueden cambiar. X se recupera desde <code>!SpriteIndex</code>. Los tres quedan en 8 bits.
| <code>$00-$01</code> y los temporales utilizados por la carga de colores; también los de efectos cuando corresponde.
|-
| <code>!ConcatenateRGBPaletteEffectToGlobal</code> y variante HSL
| 16 bits.
| A e Y pueden cambiar. Aunque X recibe una paleta al entrar, al volver contiene <code>!SpriteIndex</code>. Los tres quedan en 8 bits.
| Los temporales de efectos, <code>$05-$06</code> y <code>$F0-$F3</code>.
|}

PIXI mantiene <code>!SpriteIndex</code> como el índice del sprite actual. Si cambias X temporalmente, las llamadas que recuperan ese índice no conservan necesariamente el X que tú les entregaste. En particular, después de concatenar un efecto, X vuelve a identificar al sprite, no a su paleta. Los aliases de PIXI realizan la llamada y después continúan en la instrucción siguiente; el <code>RTS</code> de los ejemplos pertenece a la rutina del sprite.

=== RenderBox ===

<code>!RenderBox</code> comprueba si el sprite está en pantalla o lo bastante cerca de sus bordes como para seguir dibujándose. Se utiliza al comienzo de la rutina principal para decidir si ejecutar solo su lógica (short routine) o también cargar sus gráficos, manejar su paleta y dibujarlo (long routine).

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalRenderBox()</code>.
* Cluster sprite: <code>%DXClusterRenderBox()</code>.
* Extended sprite: <code>%DXExtendedRenderBox()</code>.

'''Entradas'''

* X: índice del sprite.
* <code>!RenderXDistanceOutOfScreen,x</code> y <code>!RenderYDistanceOutOfScreen,x</code>: distancias horizontal y vertical permitidas fuera de la pantalla.

'''Resultado'''

* Carry activado: el sprite está en pantalla o dentro de la distancia permitida fuera de sus bordes; se debe ejecutar la long routine.
* Carry desactivado: el sprite está demasiado lejos de la pantalla para dibujarse; se debe ejecutar la short routine.

Cuando el sprite está demasiado lejos, establece <code>!Palette</code>, <code>!LastVersion</code>, <code>!LastPoseIndex</code> y <code>!LastPoseHashIndex</code> en <code>$FF</code>. Esto indica que deberá volver a obtener su paleta y su pose cuando se acerque a la pantalla. También guarda en <code>!LastFlip</code> el volteo que resulta de combinar <code>!GlobalFlip</code> y <code>!LocalFlip</code>. En sprites normales actualiza además las variables que indican si está fuera de pantalla horizontal o verticalmente.

'''Ejemplo'''

<pre>
print "INIT ",pc
LDA.b #!RenderBoxXDistanceOutOfScreenMySprite
STA !RenderXDistanceOutOfScreen,x
LDA.b #!RenderBoxYDistanceOutOfScreenMySprite
STA !RenderYDistanceOutOfScreen,x
; Aquí va el resto de la inicialización del sprite
RTL

SpriteCode:
!RenderBox
BCS .LongRoutine

.ShortRoutine
LDA #$00
%SubOffScreen()
; Aquí va la lógica de tu sprite
RTS

.LongRoutine
; Aquí van el manejo de paletas, poses y dibujo
; y la lógica de tu sprite
RTS
</pre>

La llamada a <code>%SubOffScreen()</code> del ejemplo corresponde a sprites normales y recibe en A un valor entre 0 y 7 para seleccionar la configuración de eliminación fuera de pantalla. El ejemplo utiliza 0, el valor habitual. Se recomienda utilizarla en la short routine; dentro de la long routine resulta redundante.

Los defines <code>!RenderBoxXDistanceOutOfScreenMySprite</code> y <code>!RenderBoxYDistanceOutOfScreenMySprite</code> se generan desde el DrawInfo y se guardan en <code>DXDefines.asm</code>. El nombre del recurso se normaliza en PascalCase: se eliminan separadores como espacios, guiones bajos y guiones, y se escribe en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_sprite</code> se convierte en <code>MySprite</code>. Si el sprite utiliza varios DrawInfo, utiliza la mayor distancia horizontal y la mayor distancia vertical entre ellos.

=== PaletteAssignment ===

<code>!PaletteAssignment</code> selecciona una paleta del DynamicInfo usando <code>!Version,x</code>, le asigna una de las paletas de sprites 8-F y carga sus colores cuando hace falta. Si el sprite ya tiene esa paleta, mantiene su temporizador de uso en 2 para evitar que otro recurso la reemplace. Debe llamarse en cada frame de la long routine; esto no significa que los colores vuelvan a cargarse cada vez.

Si el bit <code>E</code> de <code>!PaletteOption,x</code> está activado (<code>$80</code>), también procesa los efectos globales de paleta correspondientes. Si está desactivado, la paleta queda excluida del efecto global.

'''Cómo se elige la paleta'''

<code>!Version,x</code> selecciona una paleta de la lista del DynamicInfo: 0 elige la primera, 1 la segunda, etc. Por ejemplo, si la lista contiene una paleta roja y otra azul, las versiones 0 y 1 seleccionan esos colores. El sprite también puede usar esta variable para cambiar su comportamiento; la rutina de paletas solo la utiliza para elegir los colores.

<code>!PaletteOption,x</code> indica qué paleta de sprites se permite utilizar y si sus colores reciben el efecto global. Su formato es <code>EPPP----</code>:

* <code>E</code>: 0 excluye la paleta del efecto global; 1 permite aplicarlo.
* <code>PPP</code>: con asignación manual, selecciona una paleta entre 8 y F. <code>000</code> elige la 8, <code>001</code> la 9, y así hasta <code>111</code> para la F.
* Con asignación automática, <code>PPP = 000</code> permite buscar entre las ocho paletas. Un valor <code>0XX</code> distinto de <code>000</code> limita la búsqueda a las paletas 8-B; un valor <code>1XX</code> la limita a las C-F.
* Los cuatro bits bajos no se utilizan para estas opciones.

<code>!PaletteAssignmentOption,x</code> decide quién elige el destino y si se cargan colores. Su formato es <code>--AA----</code>:

* <code>AA = 00</code> (<code>$00</code>): automático. Dynamic Xtreme elige una de las paletas permitidas y carga los colores del DynamicInfo.
* <code>AA = 01</code> (<code>$10</code>): manual. Utiliza la paleta indicada en <code>PPP</code> y carga los colores del DynamicInfo.
* <code>AA = 10</code> (<code>$20</code>): manual sin carga. Utiliza la paleta indicada en <code>PPP</code> con los colores que ya tiene el nivel.

En sprites normales, <code>!PaletteOption,x</code> es <code>!ExtraByte1,x</code> y <code>!PaletteAssignmentOption,x</code> es <code>!ExtraProp2,x</code>. Lo habitual es usar el primer Extra Byte con formato <code>EPPPVVVV</code> y copiar sus cuatro bits bajos a <code>!Version,x</code> durante el INIT. Así se puede elegir la versión desde Lunar Magic. En cluster y extended, el código que crea el sprite debe establecer estas variables.

Por ejemplo, con asignación manual, <code>!PaletteOption,x = $A0</code> utiliza la paleta A y permite el efecto global. Si <code>!Version,x = 1</code>, carga en ella la segunda paleta de la lista del DynamicInfo.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalPaletteAssignment()</code>.
* Cluster sprite: <code>%DXClusterPaletteAssignment()</code>.
* Extended sprite: <code>%DXExtendedPaletteAssignment()</code>.

'''Entradas'''

* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> correspondiente al DynamicInfo que contiene las paletas.
* X: índice del sprite.
* <code>!Version,x</code>: índice de la paleta dentro de la tabla.
* <code>!LastVersion,x</code>: última versión procesada. Se compara con <code>!Version,x</code> para detectar cambios y debe inicializarse en <code>$FF</code>.
* <code>!PaletteOption,x</code>: selección de paleta y participación en el efecto global.
* <code>!PaletteAssignmentOption,x</code>: asignación automática, manual o manual sin carga.

'''Resultado'''

* Carry activado: el sprite puede dibujarse con la paleta asignada.
* Carry desactivado: el sprite todavía no tiene una paleta lista para dibujar.
* <code>!Palette,x</code>: paleta asignada, con valores de <code>$00</code> a <code>$0E</code> de dos en dos para las paletas 8-F.
* <code>!LastVersion,x</code>: se actualiza con <code>!Version,x</code> cuando se procesa la nueva asignación.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignment
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y se guarda en <code>DXDefines.asm</code>. El nombre del recurso se normaliza en PascalCase eliminando separadores y poniendo en mayúscula la inicial de cada palabra: <code>my_sprite</code> se convierte en <code>MySprite</code>.

=== PaletteAssignmentNoUpload ===

<code>!PaletteAssignmentNoUpload</code> elige la paleta igual que <code>!PaletteAssignment</code>, pero deja pendiente la carga de los colores. Se utiliza cuando primero necesitas modificar la paleta, por ejemplo aplicando un efecto local y combinándolo con el global. Si ya estaba asignada, mantiene su temporizador de uso en 2 para evitar que otro recurso la reemplace.

El bit <code>E</code> de <code>!PaletteOption,x</code> (<code>$80</code>) también determina si la paleta participa en los efectos globales. Esta variante prepara la asignación y la paleta base; la aplicación final de los efectos y la carga se completan mediante la rutina posterior, como <code>!ConcatenateRGBPaletteEffectToGlobal</code> o <code>!ConcatenateHSLPaletteEffectToGlobal</code>.

<code>!Version,x</code> elige la paleta del DynamicInfo: 0 para la primera, 1 para la segunda, etc. <code>!PaletteOption,x</code> utiliza <code>EPPP----</code>: E permite el efecto global y PPP selecciona la paleta 8-F en modo manual, o el grupo donde buscarla en modo automático. En automático, <code>000</code> permite todas, <code>0XX</code> distinto de cero permite 8-B y <code>1XX</code> permite C-F.

<code>!PaletteAssignmentOption,x</code> utiliza <code>--AA----</code>: <code>$00</code> elige el destino automáticamente, <code>$10</code> usa el indicado en PPP y <code>$20</code> utiliza los colores que ya tiene el nivel. Para preparar una paleta que después recibirá un efecto local, utiliza uno de los modos que toman los colores del DynamicInfo: automático o manual con carga.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalPaletteAssignmentNoUpload()</code>.
* Cluster sprite: <code>%DXClusterPaletteAssignmentNoUpload()</code>.
* Extended sprite: <code>%DXExtendedPaletteAssignmentNoUpload()</code>.

'''Entradas'''

* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> del DynamicInfo que contiene las paletas.
* X: índice del sprite.
* <code>!Version,x</code>, <code>!PaletteOption,x</code> y <code>!PaletteAssignmentOption,x</code>: mismas opciones que en <code>!PaletteAssignment</code>.
* <code>!LastVersion,x</code>: última versión procesada, utilizada para detectar cambios respecto de <code>!Version,x</code>. Debe inicializarse en <code>$FF</code>.

'''Resultado'''

* Carry activado: el sprite tiene una paleta asignada; desactivado si no pudo obtenerse.
* <code>!Palette,x</code>: paleta asignada.
* <code>!LastVersion,x</code>: se actualiza con <code>!Version,x</code> cuando se procesa la nueva asignación.
* <code>$00-$01</code>: número que identifica la paleta elegida del DynamicInfo, cuando se utiliza un modo que carga sus colores.
* <code>$02-$04</code>: dirección de la paleta base en ROM.
* Y = 1: se acaba de asignar la paleta y hay que calcular su efecto; Y = 0: no es necesario recalcularlo por una asignación nueva. Entrega este valor a la rutina de concatenación.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

; Aquí se prepara y concatena el efecto.
; Conserva Y y la dirección de $02-$04 para esa llamada.
.Return
RTS
</pre>

<code>$00-$01</code> dice qué paleta del DynamicInfo se eligió; <code>!Palette,x</code> dice cuál de las paletas 8-F utilizará el sprite para dibujarse. Los datos de <code>$00-$04</code> solo se preparan cuando la rutina lee la paleta del DynamicInfo. Si usas el modo manual sin carga, deshabilitaste los cambios de paleta o la llamada no se procesa en el modo de juego actual, no utilices esos datos como resultado de la llamada.

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase: <code>my_sprite</code> pasa a <code>MySprite</code>, eliminando los separadores.

=== Upload ===

<code>!Upload</code> consigue los gráficos de la pose que el sprite quiere mostrar. La pose se selecciona sumando <code>!PoseIndex,x</code> al ID dinámico recibido en A. Si sus gráficos ya están en VRAM, solo actualiza su registro de último uso para evitar que sean sobrescritos. Si todavía no están, solicita su carga. Debe llamarse en cada frame de la long routine.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalUpload()</code>.
* Cluster sprite: <code>%DXClusterUpload()</code>.
* Extended sprite: <code>%DXExtendedUpload()</code>.

'''Entradas'''

* A de 16 bits: ID dinámico base.
* X: índice del sprite.
* <code>!PoseIndex,x</code>: índice que se suma al ID base.
* <code>!GlobalFlip,x</code> y <code>!LocalFlip,x</code>: volteos que se combinarán para dibujar.

'''Resultado'''

* Carry activado: el sprite tiene una pose disponible para dibujar. Puede ser la solicitada o la anterior si todavía no fue posible cargar la nueva.
* Carry desactivado: el sprite todavía no tiene una pose disponible.
* <code>!LastPoseIndex,x</code>, <code>!LastPoseHashIndex,x</code> y <code>!LastFlip,x</code>: estado de la pose disponible para dibujar.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
!Upload
RTS
</pre>

<code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase: se eliminan separadores y se escribe en mayúscula la inicial de cada palabra, como <code>my_sprite</code> → <code>MySprite</code>.

=== UploadWithoutPoseOffset ===

<code>!UploadWithoutPoseOffset</code> solicita directamente el ID dinámico entregado en A, sin sumarle <code>!PoseIndex</code>. Como <code>!Upload</code>, reutiliza los gráficos si ya están en VRAM y puede seguir mostrando la pose anterior mientras no consiga cargar la nueva.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalUploadWithoutPoseOffset()</code>.
* Cluster sprite: <code>%DXClusterUploadWithoutPoseOffset()</code>.
* Extended sprite: existe <code>%DXExtendedUploadWithoutPoseOffset()</code>, pero actualmente <code>ExtendedSpriteDefines.asm</code> no publica el alias <code>!UploadWithoutPoseOffset</code>.

'''Entradas'''

* A de 16 bits: ID dinámico exacto.
* X: índice del sprite.
* <code>!GlobalFlip,x</code> y <code>!LocalFlip,x</code>: volteos del sprite.

'''Resultado'''

* Carry activado: el sprite tiene una pose disponible para dibujar; desactivado si todavía no tiene ninguna.
* Guarda la pose que se puede dibujar en <code>!LastPoseIndex,x</code> y la ubicación de sus gráficos en <code>!LastPoseHashIndex,x</code>, igual que <code>!Upload</code>.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite003
!UploadWithoutPoseOffset
RTS
</pre>

<code>!DynamicPoseIDMySprite003</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre usa PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

=== DXDraw ===

<code>!DXDraw</code> dibuja una pose utilizando los gráficos dinámicos disponibles para el sprite.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalDraw()</code>.
* Cluster sprite: <code>%DXClusterDraw()</code>.
* Extended sprite: <code>%DXExtendedDraw()</code>.

'''Entradas'''

* A de 16 bits: ID de la pose de dibujo.
* X: índice del sprite.
* <code>!PropParam</code> (<code>$52</code>): propiedades adicionales, con formato <code>YXCC----</code>.
* <code>!MaxTilePriorityParam</code> (<code>$0A</code>): prioridad máxima de los tiles; <code>$00</code> máxima, <code>$01</code> alta, <code>$02</code> propia del tipo de sprite y <code>$03</code> mínima.
* <code>!Palette,x</code>, <code>!LastFlip,x</code> y <code>!LastPoseHashIndex,x</code>: paleta, volteo y ubicación de los gráficos disponibles.

'''Resultado'''

Dibuja la pose en pantalla. Si <code>!LastPoseHashIndex,x</code> contiene <code>$FF</code>, no dibuja. A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
Draw:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDraw
RTS
</pre>

En este ejemplo, las poses deben estar en el mismo orden en el DrawInfo y el DynamicInfo. Se utiliza <code>!LastPoseIndex</code> porque indica qué pose se puede dibujar: si la nueva todavía no se pudo cargar, seguirá mostrando la anterior.

<code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>. Los nombres de recurso y pose se normalizan en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>. Este ID de dibujo es distinto de los IDs <code>!DynamicPoseID...</code> del DynamicInfo.

=== DXDrawWithOffset ===

<code>!DXDrawWithOffset</code> permite dibujar la pose unos píxeles a la derecha, izquierda, arriba o abajo de la posición del sprite. Solo mueve el dibujo; el sprite sigue moviéndose y chocando en su posición original.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalDrawWithOffset()</code>.
* Cluster sprite: <code>%DXClusterDrawWithOffset()</code>.
* Extended sprite: <code>%DXExtendedDrawWithOffset()</code>.

'''Entradas'''

* Las mismas entradas de <code>!DXDraw</code>.
* <code>!XOffsetParam</code> (<code>$8A</code>): desplazamiento horizontal de 8 bits con signo.
* <code>!YOffsetParam</code> (<code>$8B</code>): desplazamiento vertical de 8 bits con signo.

'''Resultado'''

Dibuja igual que <code>!DXDraw</code>, pero suma los desplazamientos que preparaste. Un valor positivo en <code>!XOffsetParam</code> mueve el dibujo a la derecha; en <code>!YOffsetParam</code>, hacia abajo. Los valores negativos lo mueven a la izquierda o hacia arriba.

'''Ejemplo'''

<pre>
Draw:
LDA #$08
STA !XOffsetParam
LDA #$F8
STA !YOffsetParam
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDrawWithOffset
RTS
</pre>

El ejemplo desplaza el dibujo 8 píxeles a la derecha y 8 hacia arriba. <code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>; el nombre se normaliza en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>.

=== ReplacePalette ===

<code>!ReplacePalette</code> cambia los colores de la paleta que el sprite ya tiene asignada, sin cambiar su ID de asignación. Por ejemplo, permite sustituir su paleta normal por otra durante un estado especial. Como varios sprites pueden compartir esa paleta, todos ellos verán el cambio. Llámala cuando necesites cambiar los colores; repetirla cada frame obliga al sistema a volver a preparar la paleta y sus efectos.

Suele utilizarse después de <code>!PaletteAssignmentNoUpload</code>: primero se asigna la paleta sin cargar sus colores y después se reemplazan por los que quieres mostrar. Antes de llamar a <code>!ReplacePalette</code>, coloca en <code>$02-$04</code> la dirección de los nuevos colores.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalReplacePalette()</code>.
* Cluster sprite: <code>%DXClusterReplacePalette()</code>.
* Extended sprite: <code>%DXExtendedReplacePalette()</code>.

'''Entradas'''

* X: índice del sprite.
* A en modo de 8 bits.
* <code>$02-$04</code>: dirección ROM de la nueva paleta en BGR555.
* <code>!Palette,x</code>: paleta ya asignada.
* <code>!PaletteOption,x</code>: participación en el efecto global.

'''Resultado'''

* Carry activado: se puede dibujar con la paleta; si los nuevos colores todavía no están listos, se conservan los anteriores.
* Carry desactivado: la paleta todavía no tiene colores listos para dibujar.

Mantiene el mismo ID de paleta, pero solicita cambiar sus colores. Al marcar que el efecto debe volver a calcularse, utiliza <code>$FFFF</code> si nunca se habían obtenido colores para dibujar, o <code>$FFFE</code> si puede seguir mostrando los anteriores mientras prepara los nuevos.

'''Ejemplo'''

<pre>
ReplaceSpritePalette:
; Ejecutar cuando se necesite cambiar una paleta ya asignada.
LDA.b #!PaletteMyAlternatePalette
STA $02
LDA.b #!PaletteMyAlternatePalette>>8
STA $03
LDA.b #!PaletteMyAlternatePalette>>16
STA $04
!ReplacePalette
RTS
</pre>

<code>!PaletteMyAlternatePalette</code> es la dirección de una paleta insertada desde los recursos declarados en un DynamicInfo y se guarda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase: <code>my_alternate_palette</code> se convierte en <code>MyAlternatePalette</code>.

=== ConcatenateRGBPaletteEffectToGlobal ===

<code>!ConcatenateRGBPaletteEffectToGlobal</code> permite que la paleta del sprite tenga un efecto RGB propio y siga siendo afectada por el efecto global. Primero aplica el efecto local, como <code>PaletteTransitionRGB</code>, y después aplica el global sobre ese resultado. Llámala después de <code>!PaletteAssignmentNoUpload</code>, que deja preparada la paleta original.

El uso habitual es asignar primero la paleta con <code>!PaletteAssignmentNoUpload</code> y, si el carry está activado, llamar a esta rutina para aplicar los efectos y completar la carga de los colores.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalConcatenateRGBPaletteEffectToGlobal()</code>.
* Cluster sprite: <code>%DXClusterConcatenateRGBPaletteEffectToGlobal()</code>.
* Extended sprite: <code>%DXExtendedConcatenateRGBPaletteEffectToGlobal()</code>.

'''Entradas'''

* A de 16 bits: ID del efecto local RGB.
* X de 8 bits: copia aquí el valor de <code>!Palette,x</code> con <code>LDA !Palette,x</code> seguido de <code>TAX</code>, como en el ejemplo.
* Y de 8 bits: conserva el valor que dejó <code>!PaletteAssignmentNoUpload</code>. El valor 1 obliga a calcular de nuevo el efecto; 0 permite reutilizar el resultado anterior si no cambió nada.
* <code>$02-$04</code>: dirección de la paleta base BGR555 preparada por la asignación.
* <code>!PaletteOption</code>: el bit <code>E</code> debe estar activado para combinar con el efecto global.

'''Resultado'''

* Carry activado: se puede dibujar con la paleta. Si el nuevo efecto todavía no está listo, se sigue mostrando el anterior.
* Carry desactivado: todavía no hay colores listos para dibujar esa paleta.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

LDA !Palette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyRGBEffect0
!ConcatenateRGBPaletteEffectToGlobal
.Return
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y <code>!PaletteEffectIDMyRGBEffect0</code> desde un archivo <code>*.paleffect</code>. Ambos quedan en <code>DXDefines.asm</code>. Sus nombres se normalizan en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>. Si se necesita Y para seleccionar el efecto mediante una tabla, conserva su valor con <code>PHY</code> y restáuralo con <code>PLY</code> antes de concatenar.

=== ConcatenateHSLPaletteEffectToGlobal ===

<code>!ConcatenateHSLPaletteEffectToGlobal</code> permite que la paleta del sprite tenga un efecto HSL propio, como <code>MixH</code>, y siga siendo afectada por el efecto global. Primero aplica el efecto local y después el global. Llámala después de <code>!PaletteAssignmentNoUpload</code>, que deja preparada la paleta original.

El uso habitual es asignar primero la paleta con <code>!PaletteAssignmentNoUpload</code> y, si el carry está activado, llamar a esta rutina para aplicar los efectos y completar la carga de los colores.

'''Rutina utilizada según el tipo de sprite'''

* Sprite normal: <code>%DXNormalConcatenateHSLPaletteEffectToGlobal()</code>.
* Cluster sprite: <code>%DXClusterConcatenateHSLPaletteEffectToGlobal()</code>.
* Extended sprite: <code>%DXExtendedConcatenateHSLPaletteEffectToGlobal()</code>.

'''Entradas'''

* A de 16 bits: ID del efecto local HSL.
* X de 8 bits: copia aquí el valor de <code>!Palette,x</code> con <code>LDA !Palette,x</code> seguido de <code>TAX</code>, como en el ejemplo.
* Y de 8 bits: conserva el valor que dejó <code>!PaletteAssignmentNoUpload</code>. El valor 1 obliga a calcular de nuevo el efecto; 0 permite reutilizar el resultado anterior si no cambió nada.
* <code>$02-$04</code>: dirección de la paleta base BGR555 preparada por la asignación.
* <code>!PaletteOption</code>: el bit <code>E</code> debe estar activado para combinar con el efecto global.

'''Resultado'''

* Carry activado: se puede dibujar con la paleta. Si el nuevo efecto todavía no está listo, se sigue mostrando el anterior.
* Carry desactivado: todavía no hay colores listos para dibujar esa paleta.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

LDA !Palette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyHSLEffect0
!ConcatenateHSLPaletteEffectToGlobal
.Return
RTS
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y <code>!PaletteEffectIDMyHSLEffect0</code> desde un archivo <code>*.paleffect</code>. Quedan en <code>DXDefines.asm</code> y utilizan nombres normalizados en PascalCase: se eliminan separadores y se escribe en mayúscula la inicial de cada palabra. Conserva Y con <code>PHY</code>/<code>PLY</code> si lo utilizas temporalmente para seleccionar el efecto.

Ambas variantes de concatenación realizan las conversiones necesarias si el efecto local y el global utilizan espacios de color diferentes. Consulta [[es/Dynamic_Xtreme_files_and_formats#Tipos_de_efectos|Tipos de efectos]] para identificar los efectos RGB y HSL.

== Rutinas y Macros Generales ==

Estas rutinas y macros permiten trabajar con los sistemas de Dynamic Xtreme desde sprites, UberASM y otros códigos. En las macros puedes indicar qué variables y valores utilizar. Si un argumento contiene una coma, como <code>!NormalPoseIndex,x</code>, escríbelo entre comillas para que Asar lo lea como un solo argumento. Utiliza <code>#</code> al entregar un valor inmediato, como <code>#$04</code>.

Aplica también las reglas de [[#Estado del CPU y memoria temporal|DBR, direct page, flags y pila]]. Los contratos de cada familia indican qué registros y temporales debes guardar si necesitas conservarlos.

=== Poses dinámicas ===

==== DynamicPoseSpaceConfig ====

'''Registros y memoria temporal:''' entra con A, X e Y en 8 bits. Modifica A y X; conserva Y y los tamaños de los registros. No utiliza scratch. Guarda y restaura DBR alrededor de la selección de configuración. No devuelve un resultado en carry. Se llama con <code>JSL</code> y retorna con <code>RTL</code>.

<code>JSL !DynamicPoseSpaceConfig</code> elige qué partes de la memoria gráfica (VRAM) puede usar Dynamic Xtreme para cargar poses dinámicas. Normalmente se llama desde el <code>init</code> de UberASM al entrar al nivel.

Los defines con las configuraciones disponibles se encuentran en <code>DXDefines.asm</code>, bajo los nombres <code>!DynamicSpaceConfig...</code>.

'''Entrada'''

* A de 8 bits: una de las configuraciones <code>!DynamicSpaceConfig...</code> de <code>DXDefines.asm</code>. Sus valores van de <code>$00</code> a <code>$1C</code>.

'''Resultado'''

Después de la llamada, Dynamic Xtreme solo puede elegir espacio dentro de las regiones seleccionadas para cargar poses nuevas. Las poses que ya estaban en VRAM no se eliminan al cambiar esta opción. Lo habitual es configurarla al entrar al nivel, antes de que los sprites soliciten sus gráficos.

'''Ejemplo'''

<pre>
init:
LDA #!DynamicSpaceConfigSP4
JSL !DynamicPoseSpaceConfig
RTL
</pre>

<code>!DynamicSpaceConfigSP4</code> es una constante publicada en <code>DXDefines.asm</code> que permite utilizar SP4. Otras opciones incluyen <code>!DynamicSpaceConfigSP3</code>, <code>!DynamicSpaceConfigSP34</code> y <code>!DynamicSpaceConfigSP234</code>. Selecciona una región que no se superponga con los gráficos estáticos utilizados por el nivel.

==== DefineDynamicSpaceConfig ====

<code>%DefineDynamicSpaceConfig()</code> permite definir qué espacios de la VRAM pueden utilizarse para poses dinámicas y cuáles quedan restringidos. Se utiliza para crear una configuración propia, en lugar de elegir una de las configuraciones predefinidas de <code>!DynamicPoseSpaceConfig</code>.

'''Parámetros'''

<pre>
%DefineDynamicSpaceConfig(init, end, restricted)
</pre>

* <code>init</code>: ID del primer bloque de 16×16 del espacio.
* <code>end</code>: ID del último bloque de 16×16 del espacio. Ambos extremos se incluyen.
* <code>restricted</code>: <code>$00</code> permite utilizar ese espacio para poses dinámicas; <code>$80</code> lo restringe y el sistema no puede elegirlo para cargar poses.

Los tres parámetros son constantes utilizadas al ensamblar y se escriben sin <code>#</code>. El primer bloque debe ser menor o igual que el último, y ambos deben estar entre <code>$00</code> y <code>$7F</code>. Por ejemplo, <code>$60</code> hasta <code>$7F</code> incluye 32 bloques.

'''Cómo se numeran los bloques'''

Para esta configuración, el espacio de gráficos de sprites se considera una cuadrícula de '''128×256 píxeles'''. La mitad superior, de 128×128, corresponde a SP1 y SP2; la mitad inferior, también de 128×128, corresponde a SP3 y SP4.

La cuadrícula se divide en bloques de 16×16: hay '''8 bloques por fila y 16 filas''', para un total de 128 bloques. Sus IDs se numeran de izquierda a derecha y después se continúa en la fila siguiente, de arriba abajo:

{| class="wikitable"
! Fila en píxeles !! Col. 0 !! Col. 1 !! Col. 2 !! Col. 3 !! Col. 4 !! Col. 5 !! Col. 6 !! Col. 7
|-
! 0–15
| <code>$00</code> || <code>$01</code> || <code>$02</code> || <code>$03</code> || <code>$04</code> || <code>$05</code> || <code>$06</code> || <code>$07</code>
|-
! 16–31
| <code>$08</code> || <code>$09</code> || <code>$0A</code> || <code>$0B</code> || <code>$0C</code> || <code>$0D</code> || <code>$0E</code> || <code>$0F</code>
|-
! 32–47
| <code>$10</code> || <code>$11</code> || <code>$12</code> || <code>$13</code> || <code>$14</code> || <code>$15</code> || <code>$16</code> || <code>$17</code>
|-
! 48–63
| <code>$18</code> || <code>$19</code> || <code>$1A</code> || <code>$1B</code> || <code>$1C</code> || <code>$1D</code> || <code>$1E</code> || <code>$1F</code>
|-
! 64–79
| <code>$20</code> || <code>$21</code> || <code>$22</code> || <code>$23</code> || <code>$24</code> || <code>$25</code> || <code>$26</code> || <code>$27</code>
|-
! 80–95
| <code>$28</code> || <code>$29</code> || <code>$2A</code> || <code>$2B</code> || <code>$2C</code> || <code>$2D</code> || <code>$2E</code> || <code>$2F</code>
|-
! 96–111
| <code>$30</code> || <code>$31</code> || <code>$32</code> || <code>$33</code> || <code>$34</code> || <code>$35</code> || <code>$36</code> || <code>$37</code>
|-
! 112–127
| <code>$38</code> || <code>$39</code> || <code>$3A</code> || <code>$3B</code> || <code>$3C</code> || <code>$3D</code> || <code>$3E</code> || <code>$3F</code>
|-
! 128–143
| <code>$40</code> || <code>$41</code> || <code>$42</code> || <code>$43</code> || <code>$44</code> || <code>$45</code> || <code>$46</code> || <code>$47</code>
|-
! 144–159
| <code>$48</code> || <code>$49</code> || <code>$4A</code> || <code>$4B</code> || <code>$4C</code> || <code>$4D</code> || <code>$4E</code> || <code>$4F</code>
|-
! 160–175
| <code>$50</code> || <code>$51</code> || <code>$52</code> || <code>$53</code> || <code>$54</code> || <code>$55</code> || <code>$56</code> || <code>$57</code>
|-
! 176–191
| <code>$58</code> || <code>$59</code> || <code>$5A</code> || <code>$5B</code> || <code>$5C</code> || <code>$5D</code> || <code>$5E</code> || <code>$5F</code>
|-
! 192–207
| <code>$60</code> || <code>$61</code> || <code>$62</code> || <code>$63</code> || <code>$64</code> || <code>$65</code> || <code>$66</code> || <code>$67</code>
|-
! 208–223
| <code>$68</code> || <code>$69</code> || <code>$6A</code> || <code>$6B</code> || <code>$6C</code> || <code>$6D</code> || <code>$6E</code> || <code>$6F</code>
|-
! 224–239
| <code>$70</code> || <code>$71</code> || <code>$72</code> || <code>$73</code> || <code>$74</code> || <code>$75</code> || <code>$76</code> || <code>$77</code>
|-
! 240–255
| <code>$78</code> || <code>$79</code> || <code>$7A</code> || <code>$7B</code> || <code>$7C</code> || <code>$7D</code> || <code>$7E</code> || <code>$7F</code>
|}

Cada columna ocupa 16 píxeles de ancho. Estos IDs identifican posiciones de bloques de 16×16 en el mapa; no son los TileCodes de 8×8 que utiliza el DrawInfo.

{| class="wikitable"
! Sección !! Bloques !! Posición en la cuadrícula
|-
| SP1 || <code>$00–$1F</code> || Primeras cuatro filas.
|-
| SP2 || <code>$20–$3F</code> || Siguientes cuatro filas.
|-
| SP3 || <code>$40–$5F</code> || Siguientes cuatro filas.
|-
| SP4 || <code>$60–$7F</code> || Últimas cuatro filas.
|}

'''Ejemplos del parche'''

Estas configuraciones utilizan los mismos rangos que las opciones predefinidas del parche. Colócalas en el <code>init</code> de UberASM, antes de que los sprites soliciten sus poses.

'''Utilizar solamente SP4:'''

<pre>
init:
; SP1, SP2 y SP3 restringidos.
%DefineDynamicSpaceConfig($00, $5F, $80)

; SP4 disponible para poses dinámicas.
%DefineDynamicSpaceConfig($60, $7F, $00)
RTL
</pre>

'''Utilizar solamente SP3:'''

<pre>
init:
; SP1 y SP2 restringidos.
%DefineDynamicSpaceConfig($00, $3F, $80)

; SP3 disponible para poses dinámicas.
%DefineDynamicSpaceConfig($40, $5F, $00)

; SP4 restringido.
%DefineDynamicSpaceConfig($60, $7F, $80)
RTL
</pre>

'''Utilizar SP3 y SP4:'''

<pre>
init:
; SP1 y SP2 restringidos.
%DefineDynamicSpaceConfig($00, $3F, $80)

; SP3 y SP4 disponibles como un solo espacio.
%DefineDynamicSpaceConfig($40, $7F, $00)
RTL
</pre>

Cada ejemplo es una alternativa: utiliza una configuración completa, cubriendo los bloques <code>$00–$7F</code> con espacios consecutivos y sin superponerlos. Restringe los bloques que utilicen el jugador, sprites estáticos u otros recursos cuyos gráficos deban mantenerse. La macro no detecta esos usos por ti.

'''Registros y resultado'''

* A debe estar en modo de 8 bits. La macro modifica A y los flags N/Z; conserva X, Y, carry, DBR y D, y no cambia el tamaño de los registros.
* Escribe la configuración en <code>DX_Dynamic_Tile_Size</code> y <code>DX_Dynamic_Tile_Offset</code>, en los extremos del espacio indicado. No utiliza scratch.
* No carga gráficos ni mueve poses que ya estén en VRAM. Utilízala para preparar el espacio al entrar al nivel.
* No devuelve éxito o fallo en carry y no incluye <code>RTS</code> ni <code>RTL</code>: el código continúa después de cada llamada. El <code>RTL</code> de los ejemplos termina el <code>init</code> de UberASM.

==== TakeDynamicRequest ====

'''Registros y memoria temporal:''' entra con A de 8 bits y X/Y de 16 bits. Al volver, A, X e Y quedan en 8 bits; sus valores pueden cambiar. X solo es un índice de caché válido si el carry está activado; no conserva el índice del sprite. Puede sobrescribir <code>$00-$0F</code> y <code>$47-$51</code> al preparar una carga nueva. Conserva DBR y D, tanto en éxito como en fallo. Se llama con <code>JSL</code> y retorna con <code>RTL</code>.

<code>JSL !TakeDynamicRequest</code> recibe el número que identifica una pose y busca sus gráficos en VRAM. Si ya están cargados, marca que siguen en uso para evitar que sean sobrescritos. Si no están, busca espacio y deja preparada su carga para el próximo NMI, el momento entre imágenes en que el juego actualiza los gráficos.

'''Entrada'''

* Y de 16 bits: ID exacto de la pose dinámica.

'''Resultado'''

* Carry activado: los gráficos ya están en VRAM o se programó su carga para el próximo NMI. X contiene el índice de la entrada de caché que guarda su ubicación.
* Carry desactivado: no hay espacio suficiente en VRAM o cargar la pose superaría el límite de bytes que se pueden transferir durante ese frame.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
RequestPose:
REP #$10
LDY #!DynamicPoseIDMySprite000
JSL !TakeDynamicRequest
BCC .Unavailable

; X contiene el índice hash de la pose solicitada.
; Aquí tu código puede guardar ese índice para dibujar la pose.
RTS
.Unavailable
; Aquí se maneja la falta de recursos.
RTS
</pre>

<code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y se guarda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores y escribiendo en mayúscula la inicial de cada palabra: <code>my_sprite</code> pasa a <code>MySprite</code>.

Esta llamada devuelve dónde quedaron registrados los gráficos, pero no lo guarda en las variables del sprite ni elige la pose anterior si la solicitud falla. Para ese manejo completo utiliza <code>!Upload</code>.

==== DynamicRoutine ====

'''Registros y memoria temporal:''' establece A, X e Y en 16 bits para sus cálculos y los deja en 8 bits al volver. Los tres registros pueden cambiar. Puede sobrescribir <code>$00-$0B</code> y <code>$47-$51</code>; <code>PoseIDBackup</code> corresponde a los dos bytes de <code>$02-$03</code> de la direct page. Conserva D y no cambia DBR: debes preparar el banco de las tablas antes de llamarla. Se llama con <code>JSL</code> y retorna con <code>RTL</code>.

<code>JSL !DynamicRoutine</code> añade a la cola de transferencias la carga de los gráficos de una pose en una posición concreta de VRAM. La copia se realiza durante NMI.

La rutina necesita saber dos cosas: qué pose copiar y dónde colocarla. Recibe el destino en A, pero obtiene el ID de la pose desde una variable interna llamada <code>PoseIDBackup</code>. <code>!TakeDynamicRequest</code> prepara esos datos antes de llamarla.

'''Datos que necesita la llamada'''

* A, en sus 8 bits bajos: posición donde comenzarán los gráficos dentro del mapa de bloques utilizado por el sistema dinámico. La rutina convierte este valor a una dirección de VRAM.
* <code>PoseIDBackup</code>: variable interna de 16 bits que contiene el ID de la pose que se va a copiar.
* DBR (registro que selecciona el banco de datos): debe tener el banco donde están las tablas de direcciones y tamaños de las poses.

Antes de llamarla, el código debe haber reservado suficiente espacio en VRAM y comprobado que la carga cabe en el límite de bytes del frame. <code>!TakeDynamicRequest</code> realiza ambas tareas.

'''Resultado'''

Lee la dirección y el tamaño de los gráficos de la pose, calcula cómo distribuirlos en el destino y agrega las copias necesarias a la cola de VRAM. A, X e Y quedan en modo de 8 bits. El carry no indica si la operación tuvo éxito.

'''Ejemplo de funcionamiento'''

Cuando un sprite solicita una pose que todavía no está en VRAM, <code>!TakeDynamicRequest</code> busca dónde colocarla. Después guarda su ID en <code>PoseIDBackup</code> y llama a <code>!DynamicRoutine</code> con la posición elegida en A. Esta última prepara la copia de los gráficos; el NMI ejecuta la transferencia.

Para cargar una pose desde el código de un sprite, utiliza <code>!Upload</code>. Si necesitas hacer la solicitud directamente mediante su ID, utiliza <code>!TakeDynamicRequest</code>. Llamar a <code>!DynamicRoutine</code> requiere preparar también la variable interna del ID, el banco de datos y el espacio de destino descritos arriba.

==== GeneralUpload ====

'''Registros y memoria temporal:''' entra con A de 16 bits y X/Y de 8 bits. Al terminar, A, X e Y quedan en 8 bits. A e Y pueden cambiar; con <code>sprite = 1</code> o <code>2</code>, X se recupera desde <code>!SpriteIndex</code>; con <code>sprite = 0</code>, no se conserva X. Puede sobrescribir <code>$00-$0F</code> y <code>$47-$51</code>, incluidos los temporales de una solicitud nueva. Conserva DBR y D. Incluye <code>RTS</code>: llama con <code>JSR</code> a la rutina que contiene la macro.

<code>%GeneralUpload()</code> realiza el mismo trabajo de carga que las rutinas para sprites, pero te permite elegir las variables donde guardar el índice de pose, el volteo y la ubicación de sus gráficos. Sirve, por ejemplo, para una entidad que necesita manejar varias poses independientes o para un código que utiliza sus propias tablas.

'''Parámetros'''

<pre>
%GeneralUpload(Pose16, checkLast, sprite, flip, safeCheck, withoutOffset,
safeLow, safeHigh, poseIndex, lastPoseIndex, lastPoseHashIndex,
globalFlip, localFlip, lastFlip)
</pre>

La firma anterior muestra el orden de los parámetros; escribe la llamada en una sola línea.

* <code>Pose16</code>: 0 utiliza índices de pose de 8 bits; 1 utiliza índices de 16 bits.
* <code>checkLast</code>: 1 permite seguir dibujando la pose anterior si no se pudo obtener la nueva; 0 desactiva esa opción.
* <code>sprite</code>: 0 para usar variables propias sin recuperar el índice del sprite; 1 para trabajar con las tablas del sprite, recuperando X desde <code>!SpriteIndex</code>; 2 funciona como 1, pero solicita la pose sin comparar ni cambiar <code>lastPoseIndex</code>.
* <code>flip</code>: 1 combina <code>globalFlip</code> y <code>localFlip</code> en <code>lastFlip</code>; 0 omite esa actualización.
* <code>safeCheck</code>: 1 evita repetir la solicitud en el mismo frame utilizando <code>safeLow</code> y <code>safeHigh</code>; 0 omite la comprobación.
* <code>withoutOffset</code>: 0 suma <code>poseIndex</code> al ID base; 1 utiliza directamente el ID recibido.
* <code>safeLow</code> y <code>safeHigh</code>: variables que guardan los bytes bajo y alto del frame de la solicitud. Se escriben incluso cuando <code>safeCheck</code> es 0.
* <code>poseIndex</code>: variable del índice de pose deseado.
* <code>lastPoseIndex</code>: variable del último índice de pose disponible.
* <code>lastPoseHashIndex</code>: variable que identifica la entrada donde Dynamic Xtreme guarda la ubicación de los gráficos en VRAM. <code>$FF</code> indica que todavía no hay gráficos disponibles.
* <code>globalFlip</code>, <code>localFlip</code> y <code>lastFlip</code>: variables del volteo global, local y efectivo.

'''Entrada adicional'''

* A de 16 bits: ID dinámico base o exacto, según <code>withoutOffset</code>.
* Para <code>sprite = 1</code> o <code>sprite = 2</code>, <code>!SpriteIndex</code> debe contener el índice del sprite.

Con <code>sprite = 2</code>, la macro solicita la pose aunque <code>poseIndex</code> y <code>lastPoseIndex</code> sean iguales, y deja <code>lastPoseIndex</code> sin modificar. Si consigue los gráficos, guarda su ubicación en <code>lastPoseHashIndex</code>. Si la solicitud falla y <code>checkLast</code> es 1, puede seguir usando los gráficos anteriores. <code>safeCheck</code> sigue controlando si se permite repetir la solicitud durante el mismo frame.

Este valor 2 no cambia el tamaño de los índices. Para utilizar variables de índice de 16 bits se selecciona <code>Pose16 = 1</code>. El ID dinámico entregado en A siempre es de 16 bits.

<code>sprite = 2</code> suele utilizarse en sprites dinámicos formados por varias piezas, como una cabeza y un cuerpo que necesitan cambiar sus gráficos al mismo tiempo. Al dejar <code>lastPoseIndex</code> sin modificar, permite que el código del sprite coordine el cambio de todas las piezas antes de actualizar el índice de pose. La macro no sincroniza las piezas por sí sola: esa coordinación la realiza el código que la llama.

'''Resultado'''

Devuelve el carry activado cuando hay una pose disponible para dibujar: la solicitada o la anterior si <code>checkLast</code> permite conservarla. Si no hay ninguna, devuelve el carry desactivado. Guarda la información de esa pose en las variables indicadas y marca sus gráficos como usados para evitar que sean sobrescritos. La macro incluye un <code>RTS</code> al final; colócala al final de una rutina llamada con <code>JSR</code>.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%GeneralUpload(0, 1, 1, 1, 1, 0, "!NormalSafeFrameLowByte,x", "!NormalSafeFrameHighByte,x", "!NormalPoseIndex,x", "!NormalLastPoseIndex,x", "!NormalLastPoseHashIndex,x", "!NormalGlobalFlip,x", "!NormalLocalFlip,x", "!NormalLastFlip,x")
</pre>

El ejemplo utiliza las tablas de un sprite normal y un índice de pose de 8 bits. <code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>; el nombre se normaliza en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>.

==== Upload (macro general) ====

'''Registros y memoria temporal:''' utiliza el mismo contrato de [[#GeneralUpload|GeneralUpload]], con <code>Pose16 = 0</code>. A entra en 16 bits, X/Y en 8 bits, y los tres quedan en 8 bits. El valor de <code>sprite</code> determina si X vuelve a cargarse desde <code>!SpriteIndex</code>. La macro incluye <code>RTS</code>.

<code>%Upload()</code> es la variante de <code>%GeneralUpload()</code> para índices de pose de 8 bits. No debe confundirse con el alias para sprites <code>!Upload</code>.

'''Parámetros'''

<pre>
%Upload(sprite, checkLast, flip, safeCheck, withoutOffset,
safeLow, safeHigh, poseIndex, lastPoseIndex, lastPoseHashIndex,
globalFlip, localFlip, lastFlip)
</pre>

Recibe los mismos datos que <code>%GeneralUpload()</code>, pero los índices guardados en las variables siempre son de 8 bits. La macro ya incluye el <code>RTS</code> que termina la rutina.

El parámetro <code>sprite</code> también admite 2: omite la comparación con <code>lastPoseIndex</code> y no actualiza esa variable, pero sí actualiza <code>lastPoseHashIndex</code> al obtener la pose. No habilita índices de 16 bits; para eso se utiliza <code>%GeneralUpload()</code> con <code>Pose16 = 1</code>.

Este modo suele usarse para coordinar sprites dinámicos con varias piezas y hacer que cambien sus gráficos al mismo tiempo. Por ejemplo, el código puede manejar por separado la carga de la cabeza y del cuerpo, y actualizar el índice de pose cuando corresponda cambiar ambas partes juntas. Como la macro deja <code>lastPoseIndex</code> sin modificar, el código del sprite puede controlar ese cambio.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%Upload(1, 1, 1, 1, 0, "!NormalSafeFrameLowByte,x", "!NormalSafeFrameHighByte,x", "!NormalPoseIndex,x", "!NormalLastPoseIndex,x", "!NormalLastPoseHashIndex,x", "!NormalGlobalFlip,x", "!NormalLocalFlip,x", "!NormalLastFlip,x")
</pre>

<code>!DynamicPoseIDMySprite000</code> es generado desde el DynamicInfo y se guarda en <code>DXDefines.asm</code>. El nombre usa PascalCase eliminando separadores: <code>my_sprite</code> pasa a <code>MySprite</code>.

==== StandardSpriteUpload ====

'''Registros y memoria temporal:''' utiliza el contrato de [[#GeneralUpload|GeneralUpload]] con <code>sprite = 1</code>. A entra en 16 bits y X/Y en 8 bits. Al volver, X contiene <code>!SpriteIndex</code>; A e Y pueden cambiar y los tres quedan en 8 bits. Comparte sus scratch y termina con <code>RTS</code>.

<code>%StandardSpriteUpload(withoutOffset, type)</code> selecciona automáticamente las tablas de Dynamic Xtreme correspondientes a un sprite normal, cluster o extended. Es la macro utilizada por las rutinas PIXI de carga.

'''Parámetros y entradas'''

* <code>withoutOffset</code>: 0 suma <code>!PoseIndex</code> al ID base; 1 utiliza el ID exacto.
* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code> o <code>"Extended"</code>.
* A de 16 bits: ID dinámico.
* <code>!SpriteIndex</code>: índice del sprite.
* Tablas de poses y volteo de Dynamic Xtreme del tipo seleccionado, inicializadas como en las rutinas <code>!Upload</code>.

'''Resultado'''

Selecciona las variables del tipo de sprite indicado. Permite conservar la pose anterior si la nueva no está lista, actualiza el volteo y evita repetir la solicitud durante el mismo frame. El carry funciona igual que en <code>!Upload</code>. La macro ya incluye el <code>RTS</code> que termina la rutina.

'''Ejemplo'''

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
%StandardSpriteUpload(0, "Normal")
</pre>

<code>!DynamicPoseIDMySprite000</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase: <code>my_sprite</code> pasa a <code>MySprite</code>, eliminando los separadores.

=== Dibujo de poses ===

Las macros de esta categoría terminan la rutina que las contiene mediante <code>RTS</code>. Los ejemplos deben llamarse con <code>JSR</code>. A debe contener el ID de dibujo con 16 bits; <code>!PropParam</code> (<code>$52</code>) y <code>!MaxTilePriorityParam</code> (<code>$0A</code>) se preparan igual que para <code>!DXDraw</code>.

==== Draw ====

'''Registros y memoria temporal:''' entra con A de 16 bits y X/Y de 8 bits. A e Y pueden cambiar. Con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code> al preparar un dibujo válido; con <code>sprite = 0</code>, no se conserva el X inicial. Si no hay pose válida, X no cambia. Los tres registros quedan en 8 bits. Puede sobrescribir <code>$00-$0F</code>, <code>$45-$4F</code> y <code>$8A</code>; con <code>offset = 1</code>, también <code>$8B-$8C</code>. Conserva DBR y D. Incluye <code>RTS</code>.

<code>%Draw()</code> dibuja una pose dinámica. En la llamada indicas qué gráficos usar, su paleta, su volteo y la posición donde quieres dibujarla.

'''Parámetros'''

<pre>
%Draw(offset, sprite, lastPoseHashIndex, lastFlip, palette, xl, xh, yl, yh)
</pre>

* <code>offset</code>: 0 utiliza las coordenadas entregadas; 1 añade <code>!XOffsetParam</code> (<code>$8A</code>) y <code>!YOffsetParam</code> (<code>$8B</code>), de 8 bits con signo.
* <code>sprite</code>: 1 recupera el índice del sprite en X desde <code>!SpriteIndex</code> antes de leer su paleta y posición; 0 omite ese paso.
* <code>lastPoseHashIndex</code>: variable que identifica dónde están registrados los gráficos de la pose en Dynamic Xtreme. Si contiene <code>$FF</code>, no se dibuja.
* <code>lastFlip</code>: variable o valor que indica el volteo con el que se dibujará.
* <code>palette</code>: variable o valor de la paleta; <code>$00</code> selecciona la 8, <code>$02</code> la 9, y así hasta <code>$0E</code> para la F.
* <code>xl</code> y <code>xh</code>: variables o valores de los bytes bajo y alto de la posición X.
* <code>yl</code> y <code>yh</code>: variables o valores de los bytes bajo y alto de la posición Y.

'''Resultado'''

Dibuja la pose con los gráficos indicados por <code>lastPoseHashIndex</code>, en la posición X e Y entregada. Puedes pasar las variables de posición de un sprite o indicar otra posición para dibujar desde UberASM u otro código.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
DrawPose:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMySprite_Frame0
%Draw(0, 1, "!NormalLastPoseHashIndex,x", "!NormalLastFlip,x", "!NormalPalette,x", "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

<code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y se guarda en <code>DXDefines.asm</code>. Los nombres se normalizan en PascalCase eliminando separadores, como <code>my_sprite</code> → <code>MySprite</code>. El ID debe corresponder a los gráficos dinámicos disponibles.

==== StandardSpriteDraw ====

'''Registros y memoria temporal:''' comparte el contrato y las scratch de [[#Draw|Draw]], con <code>sprite = 1</code>. Entra con A de 16 bits y X/Y de 8 bits. Prepara X con el índice del sprite antes de invocarla, porque lee su índice hash antes de recuperar <code>!SpriteIndex</code>. Al terminar deja los tres registros en 8 bits e incluye <code>RTS</code>.

<code>%StandardSpriteDraw(offset, type)</code> dibuja una pose dinámica utilizando las tablas de Dynamic Xtreme del tipo de sprite seleccionado.

'''Parámetros y entradas'''

* <code>offset</code>: 0 sin desplazamiento adicional; 1 utiliza los offsets de <code>$8A</code> y <code>$8B</code>.
* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code> o <code>"Extended"</code>.
* A de 16 bits: ID de dibujo.
* <code>!SpriteIndex</code>: índice del sprite.
* <code>!PropParam</code> y <code>!MaxTilePriorityParam</code>: propiedades y prioridad.
* Las tablas de paleta, último volteo e índice hash de Dynamic Xtreme del tipo seleccionado.

'''Resultado'''

El mismo que <code>%Draw()</code>, utilizando las tablas estándar. Es la macro que utilizan las rutinas PIXI <code>!DXDraw</code> y <code>!DXDrawWithOffset</code>.

Para sprites normales, las rutinas PIXI preparan los aliases de coordenadas <code>!NormalXLow</code>, <code>!NormalXHigh</code>, <code>!NormalYLow</code> y <code>!NormalYHigh</code>. Si se expande la macro directamente, también deben estar definidos, como en este ejemplo.

'''Ejemplo'''

<pre>
!NormalXLow = !SpriteXLow
!NormalXHigh = !SpriteXHigh
!NormalYLow = !SpriteYLow
!NormalYHigh = !SpriteYHigh

DrawPose:
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMySprite_Frame0
%StandardSpriteDraw(0, "Normal")
</pre>

<code>!PoseIDMySprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>. Su nombre usa PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

==== DrawStatic ====

'''Registros y memoria temporal:''' entra con A de 16 bits y X/Y de 8 bits. A e Y pueden cambiar; X se conserva, pero los tres registros quedan en 8 bits. Puede sobrescribir <code>$00-$0F</code>, <code>$45-$4F</code> y <code>$8A</code>; con <code>offset = 1</code>, también <code>$8B-$8C</code>. El parámetro <code>sprite</code> no recupera X desde <code>!SpriteIndex</code> en esta macro. Conserva DBR y D. Incluye <code>RTS</code>.

<code>%DrawStatic()</code> dibuja una pose estática, declarada con <code>.IsStatic</code> en el DrawInfo. Sus gráficos deben estar previamente cargados en las posiciones de VRAM indicadas por sus tiles.

'''Parámetros'''

<pre>
%DrawStatic(offset, sprite, lastFlip, palette, xl, xh, yl, yh)
</pre>

* <code>offset</code>: 0 sin desplazamiento adicional; 1 utiliza <code>!XOffsetParam</code> (<code>$8A</code>) y <code>!YOffsetParam</code> (<code>$8B</code>), con signo.
* <code>sprite</code>: parámetro conservado en la firma; la implementación actual de esta macro no lo utiliza.
* <code>lastFlip</code>: variable o valor que indica el volteo; <code>#$00</code> dibuja sin volteo.
* <code>palette</code>: variable o valor de paleta: <code>#$00</code> selecciona la 8, <code>#$02</code> la 9, y así hasta <code>#$0E</code> para la F.
* <code>xl</code> y <code>xh</code>: variables o valores de los bytes bajo y alto de la posición X.
* <code>yl</code> y <code>yh</code>: variables o valores de los bytes bajo y alto de la posición Y.

'''Entradas adicionales'''

* A de 16 bits: ID de dibujo estático.
* <code>!PropParam</code> (<code>$52</code>) y <code>!MaxTilePriorityParam</code> (<code>$0A</code>): propiedades y prioridad.
* <code>!Tile</code> (<code>$05</code>): número de tile, cuando todos los tiles de la pose están definidos con el valor predeterminado 0. Si el DrawInfo declara otros valores, utiliza esos tiles directamente.

'''Resultado'''

Dibuja la pose sin consultar la caché de gráficos dinámicos. No requiere <code>!LastPoseHashIndex</code> ni una llamada previa a <code>!Upload</code>.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
DrawPose:
LDA #$80
STA !Tile
LDA #$20
STA !PropParam
LDA #$02
STA !MaxTilePriorityParam
REP #$20
LDA #!PoseIDMyStaticSprite_Frame0
%DrawStatic(0, 1, #$00, #$04, "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

El ejemplo utiliza el tile <code>$80</code> si la pose está configurada para tomarlo desde <code>!Tile</code>, sin volteo y con la paleta A. <code>!PoseIDMyStaticSprite_Frame0</code> se genera desde el DrawInfo y queda en <code>DXDefines.asm</code>. Su nombre usa PascalCase eliminando separadores y poniendo en mayúscula la inicial de cada palabra: <code>my_static_sprite</code> pasa a <code>MyStaticSprite</code>.

=== Paletas ===

Estas macros permiten elegir qué paleta usa un sprite, cargar sus colores y cambiarlos durante el juego.

==== LoadPaletteIDAndAddress ====

'''Registros y memoria temporal:''' entra con A de 8 bits; la macro establece los tamaños que necesita para calcular las direcciones. Modifica A y X. Y no se utiliza, pero pasa a modo de 8 bits y pierde su byte alto si antes estaba en 16 bits. Al terminar los tres registros quedan en 8 bits. Escribe <code>$00-$04</code> y lee <code>$0E-$0F</code>. Conserva DBR y D; carry no es un indicador de éxito. La expansión continúa en la instrucción siguiente.

<code>%LoadPaletteIDAndAddress()</code> permite saber qué número identifica una paleta y dónde están guardados sus colores en la ROM. Elige una de las paletas del DynamicInfo: 0 para la primera, 1 para la segunda, etc. La llamada no carga colores en el juego; solo te entrega esos datos para usarlos después.

'''Entradas'''

* A de 8 bits: índice de la paleta dentro del DynamicInfo.
* <code>$0E-$0F</code>: guarda aquí el define <code>!MySpritePaletteTableOffset</code> de tu DynamicInfo, con 16 bits, como muestra el ejemplo.

'''Resultado'''

* <code>$00-$01</code>: ID de la paleta.
* <code>$02-$04</code>: dirección de sus colores en ROM, en formato BGR555.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre>
REP #$20
LDA #!MySpritePaletteTableOffset
STA $0E
SEP #$20

LDA #$01 ; Segunda paleta del DynamicInfo
%LoadPaletteIDAndAddress()
; $00-$01 contiene su ID y $02-$04 su dirección ROM.
</pre>

En PIXI también puede llamarse mediante <code>%DXLoadPaletteIDAndAddress()</code>, con las mismas entradas y resultados. Esta variante llama a una rutina compartida y después continúa con el código siguiente.

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza eliminando espacios, guiones bajos y guiones, y poniendo en mayúscula la inicial de cada palabra: <code>my_sprite</code> pasa a <code>MySprite</code>.

==== PaletteAssignment (macro general) ====

'''Registros y memoria temporal:''' entra con X/Y de 8 bits y A de 16 bits cuando <code>PalettesChange</code> está habilitado. Si está deshabilitado, entra con A de 8 bits y no se utiliza el offset de tabla. A e Y pueden cambiar; con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code> cuando se utiliza internamente; con <code>sprite = 0</code>, no se conserva X. Al volver, los tres quedan en 8 bits. Puede sobrescribir <code>$00-$0F</code>, <code>$D5</code> y los temporales de efectos cuando corresponda. Conserva DBR y D. La macro termina con <code>RTL</code>.

<code>%PaletteAssignment()</code> asigna y carga una paleta igual que <code>!PaletteAssignment</code>, pero permite indicar las variables donde se guardan sus opciones y su estado. Se puede usar para manejar una paleta adicional de un sprite o para un código con variables propias.

Si la paleta ya estaba asignada, mantiene su temporizador de uso en 2 para que no sea reemplazada mientras se utiliza. Si el bit <code>$80</code> de las opciones está activado, también aplica el efecto global correspondiente.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteAssignment(sprite, palette, paletteAssignment, paletteOption, paletteVersion, paletteLastVersion, manualIDGroup, manualID)
</pre>

* <code>sprite</code>: 1 utiliza <code>!SpriteIndex</code> para acceder a las tablas del sprite; 0 permite usar variables independientes del índice del sprite.
* <code>palette</code>: variable que recibe la paleta asignada. Debe comenzar en <code>$FF</code>. Los valores <code>$00</code>, <code>$02</code>, ..., <code>$0E</code> corresponden a las paletas 8-F.
* <code>paletteAssignment</code>: variable o valor con formato <code>--AA----</code>. <code>$00</code> permite que Dynamic Xtreme elija el destino y cargue los colores; <code>$10</code> utiliza el destino que tú indicas y carga los colores; <code>$20</code> utiliza ese destino con los colores que ya tiene el nivel.
* <code>paletteOption</code>: variable o valor con formato <code>EPPP----</code>. E = 1 permite aplicar el efecto global; E = 0 lo excluye. En modo manual, PPP elige entre la paleta 8 (<code>000</code>) y la F (<code>111</code>). En automático, <code>000</code> permite todas, <code>0XX</code> distinto de cero permite 8-B y <code>1XX</code> permite C-F. Los cuatro bits bajos no se usan para estas opciones.
* <code>paletteVersion</code>: variable o valor que selecciona una paleta de la lista del DynamicInfo: 0 para la primera, 1 para la segunda, etc. En las rutinas de sprites corresponde a <code>!Version,x</code>.
* <code>paletteLastVersion</code>: variable que guarda la última versión procesada. Debe comenzar en <code>$FF</code>.
* <code>manualIDGroup</code> y <code>manualID</code>: juntos forman el número con el que el sistema reconoce la paleta en los modos manuales. El primero indica el grupo: <code>#$FE</code> para normal, <code>#$FC</code> para cluster y <code>#$FD</code> para extended. El segundo indica el tipo de sprite; en uno normal se utiliza <code>!CustomSpriteNumber,x</code>, como en el ejemplo.

También puedes crear grupos propios: por ejemplo, usar <code>manualIDGroup = #$FB</code> para el jugador y <code>#$FA</code> para otro tipo de entidad. Son ejemplos, no valores predefinidos de Dynamic Xtreme. Elige valores que no estés utilizando para otro grupo y usa <code>manualID</code> para distinguir los recursos dentro de cada uno. Los grupos <code>$FE</code>, <code>$FD</code> y <code>$FC</code> ya son utilizados por las rutinas de sprites normales, extended y cluster, respectivamente.

'''Entrada adicional'''

* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> del DynamicInfo que contiene las paletas.
* Si <code>sprite = 1</code>, <code>!SpriteIndex</code> debe contener el índice del sprite.

'''Resultado'''

* Carry activado: hay una paleta con la que se puede dibujar; desactivado si todavía no hay ninguna.
* Guarda el número de paleta en <code>palette</code> y actualiza <code>paletteLastVersion</code> cuando procesa la versión.
* A, X e Y quedan en modo de 8 bits.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
%PaletteAssignment(1, "!NormalPalette,x", "!NormalPaletteAssignment,x", "!NormalPaletteOption,x", "!NormalVersion,x", "!NormalLastVersion,x", #$FE, "!CustomSpriteNumber,x")
</pre>

El ejemplo utiliza las variables de un sprite normal. <code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

Llama a la rutina del ejemplo con <code>JSL PaletteManagement</code>. La macro ya incluye el <code>RTL</code> que termina la rutina, por lo que no debes añadir código después de ella.

==== PaletteAssignmentNoUpload (macro general) ====

'''Registros y memoria temporal:''' comparte el contrato de [[#PaletteAssignment (macro general)|PaletteAssignment (macro general)]]. Además de su carry, devuelve Y como se indica abajo; no conserves en Y otro dato que necesites después. Las salidas de <code>$00-$04</code> solo son válidas si se leyó una paleta del DynamicInfo. Termina con <code>RTL</code>.

<code>%PaletteAssignmentNoUpload()</code> elige una paleta como <code>%PaletteAssignment()</code>, pero deja pendiente la carga de sus colores. Permite aplicar después un efecto local y combinarlo con el global.

'''Parámetros y entradas'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteAssignmentNoUpload(sprite, palette, paletteAssignment, paletteOption, paletteVersion, paletteLastVersion, manualIDGroup, manualID)
</pre>

Los parámetros son los mismos que en <code>%PaletteAssignment()</code>. A recibe el offset de la tabla con 16 bits. <code>palette</code> y <code>paletteLastVersion</code> deben comenzar en <code>$FF</code>.

<code>paletteVersion</code> elige los colores de la lista del DynamicInfo: 0 para la primera paleta, 1 para la segunda, etc. <code>paletteAssignment</code> decide el modo: <code>$00</code> automático, <code>$10</code> manual y <code>$20</code> manual sin cargar colores. <code>paletteOption</code> utiliza <code>EPPP----</code>: E permite el efecto global y PPP selecciona la paleta 8-F en manual. En automático, <code>000</code> permite todas, <code>0XX</code> distinto de cero permite 8-B y <code>1XX</code> permite C-F. Para aplicar después un efecto local sobre los colores del DynamicInfo, utiliza el modo automático o manual con carga.

'''Resultado'''

* Carry activado: hay una paleta asignada; desactivado si no pudo obtenerse.
* <code>palette</code>: número de la paleta asignada, de dos en dos entre <code>$00</code> y <code>$0E</code>.
* <code>paletteLastVersion</code>: última versión procesada.
* <code>$00-$01</code>: ID de la paleta seleccionada del DynamicInfo.
* <code>$02-$04</code>: dirección ROM de sus colores.
* Y = 1 indica que se acaba de asignar la paleta y hay que calcular su efecto. Y = 0 indica que no hace falta recalcularlo por una asignación nueva.
* A, X e Y quedan en modo de 8 bits.

Usa los datos de <code>$00-$04</code> solo cuando la llamada leyó una paleta del DynamicInfo. Si usas una paleta del nivel sin cargarla, deshabilitaste los cambios de paleta o la llamada no se procesa en el modo de juego actual, esas direcciones pueden contener datos de otro código.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
AssignPaletteForEffect:
REP #$20
LDA #!MySpritePaletteTableOffset
%PaletteAssignmentNoUpload(1, "!NormalPalette,x", "!NormalPaletteAssignment,x", "!NormalPaletteOption,x", "!NormalVersion,x", "!NormalLastVersion,x", #$FE, "!CustomSpriteNumber,x")
</pre>

Después de llamar a <code>AssignPaletteForEffect</code> con <code>JSL</code>, comprueba el carry y aplica el efecto usando los datos devueltos. Conserva Y y <code>$02-$04</code> para la llamada de concatenación.

La macro ya termina la rutina con <code>RTL</code>. El código que aplica el efecto va después de la llamada <code>JSL AssignPaletteForEffect</code>, no después de la macro dentro de esa rutina.

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre usa PascalCase eliminando separadores: <code>my_sprite</code> pasa a <code>MySprite</code>.

==== StandardSpritePaletteAssignment ====

'''Registros y memoria temporal:''' comparte el contrato de [[#PaletteAssignment (macro general)|PaletteAssignment (macro general)]], con <code>sprite = 1</code>. Entra con X preparado para leer las tablas del sprite y con <code>!SpriteIndex</code> correspondiente al mismo sprite. Recupera X desde ese índice cuando lo utiliza internamente; A e Y pueden cambiar. Incluye <code>RTL</code>.

<code>%StandardSpritePaletteAssignment()</code> utiliza las variables de paleta del tipo de sprite indicado. Es la macro utilizada por las rutinas PIXI de asignación.

'''Parámetros y entradas'''

<pre>
%StandardSpritePaletteAssignment(type, manualIDGroup, manualID)
</pre>

* <code>type</code>: <code>"Normal"</code>, <code>"Cluster"</code> o <code>"Extended"</code>.
* <code>manualIDGroup</code>: <code>#$FE</code> para normal, <code>#$FC</code> para cluster o <code>#$FD</code> para extended.
* También puedes elegir un grupo propio, por ejemplo <code>#$FB</code> para el jugador o <code>#$FA</code> para otro tipo de entidad, siempre que esos valores no estén siendo utilizados por otro grupo de tu proyecto.
* <code>manualID</code>: variable o valor que identifica el tipo de sprite en los modos manuales.
* A de 16 bits: el define <code>!MySpritePaletteTableOffset</code> del DynamicInfo que contiene las paletas.
* <code>!SpriteIndex</code>: índice del sprite.
* Las variables de Dynamic Xtreme para paleta, opciones, versión y última versión del tipo seleccionado, preparadas como en <code>!PaletteAssignment</code>.

'''Resultado'''

El mismo que <code>!PaletteAssignment</code>: guarda la paleta asignada en la tabla del sprite y devuelve el carry activado cuando se puede dibujar con ella.

La macro ya incluye un <code>RTL</code>. Llama a la rutina del ejemplo con <code>JSL PaletteManagement</code> y no añadas código después de la macro.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
%StandardSpritePaletteAssignment("Normal", #$FE, "!CustomSpriteNumber,x")
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase: <code>my_sprite</code> pasa a <code>MySprite</code> al eliminar los separadores.

==== StandardSpritePaletteAssignmentNoUpload ====

'''Registros y memoria temporal:''' comparte el contrato de [[#PaletteAssignmentNoUpload (macro general)|PaletteAssignmentNoUpload (macro general)]], con <code>sprite = 1</code>. X y <code>!SpriteIndex</code> deben identificar al mismo sprite al entrar. Conserva Y y <code>$02-$04</code> de su resultado si vas a concatenar un efecto. Incluye <code>RTL</code>.

<code>%StandardSpritePaletteAssignmentNoUpload()</code> utiliza las variables del tipo de sprite seleccionado para asignar la paleta, dejando pendiente la carga de los colores.

'''Parámetros y entradas'''

<pre>
%StandardSpritePaletteAssignmentNoUpload(type, manualIDGroup, manualID)
</pre>

Recibe los mismos parámetros y datos que <code>%StandardSpritePaletteAssignment()</code>. A debe contener el offset de la tabla de paletas con 16 bits.

'''Resultado'''

El mismo que <code>!PaletteAssignmentNoUpload</code>: guarda la paleta asignada y devuelve el carry, Y, el ID en <code>$00-$01</code> y la dirección en <code>$02-$04</code>, con las condiciones indicadas en esa entrada.

La macro ya incluye un <code>RTL</code>. Llama a la rutina del ejemplo con <code>JSL AssignPaletteForEffect</code>. El código que aplica el efecto va después de esa llamada.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
AssignPaletteForEffect:
REP #$20
LDA #!MySpritePaletteTableOffset
%StandardSpritePaletteAssignmentNoUpload("Normal", #$FE, "!CustomSpriteNumber,x")
</pre>

<code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase eliminando separadores: <code>my_sprite</code> se convierte en <code>MySprite</code>.

==== ReplacePalette (macro general) ====

'''Registros y memoria temporal:''' entra con A, X e Y de 8 bits y con el puntero de origen preparado en <code>$02-$04</code>. A e Y pueden cambiar; con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code>; con <code>sprite = 0</code>, no se conserva X. Los tres quedan en 8 bits. Puede sobrescribir <code>$00-$01</code> y los temporales de efectos cuando corresponda. Conserva DBR y D. Termina con <code>RTL</code>.

<code>%ReplacePalette()</code> sustituye los colores de una paleta que ya estás usando. Hace lo mismo que <code>!ReplacePalette</code>, pero tú eliges qué variables leer. Si otros sprites o códigos usan esa misma paleta, también verán los nuevos colores.

Suele utilizarse después de una asignación sin carga, como <code>%PaletteAssignmentNoUpload()</code>. Primero obtienes la paleta asignada y después preparas en <code>$02-$04</code> la dirección de los colores que quieres usar para reemplazarla.

'''Parámetros y entradas'''

<pre>
%ReplacePalette(sprite, paletteOption, palette)
</pre>

* <code>sprite</code>: 1 obtiene el índice del sprite desde <code>!SpriteIndex</code>; 0 utiliza variables independientes de ese índice.
* <code>paletteOption</code>: variable o valor de las opciones de paleta. El bit <code>$80</code> indica si se aplica el efecto global.
* <code>palette</code>: variable o valor de la paleta de destino, entre <code>$00</code> y <code>$0E</code> de dos en dos.
* <code>$02-$04</code>: dirección ROM de los nuevos colores en BGR555.
* A en modo de 8 bits.

'''Resultado'''

Cambia los colores sin cambiar el ID de asignación. Devuelve el carry activado cuando hay colores con los que se puede dibujar, incluidos los anteriores si el cambio todavía no se pudo completar. El carry queda desactivado si todavía no hay un resultado disponible.

Llámala cuando cambien los colores que quieres mostrar. Repetir la llamada cada frame obliga a preparar de nuevo la paleta y sus efectos.

Llama a la rutina del ejemplo con <code>JSL ReplaceSpritePalette</code>. La macro ya incluye el <code>RTL</code> que termina la rutina.

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
ReplaceSpritePalette:
LDA.b #!PaletteMyAlternatePalette
STA $02
LDA.b #!PaletteMyAlternatePalette>>8
STA $03
LDA.b #!PaletteMyAlternatePalette>>16
STA $04
%ReplacePalette(1, "!NormalPaletteOption,x", "!NormalPalette,x")
</pre>

<code>!PaletteMyAlternatePalette</code> es la dirección de una paleta insertada a partir de los recursos del DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza eliminando separadores y poniendo en mayúscula la inicial de cada palabra: <code>my_alternate_palette</code> pasa a <code>MyAlternatePalette</code>.

==== Cargar colores con TransferPalette ====

Estas macros cargan colores en la paleta que tú elijas, sin asignación automática. Puedes usarlas para cambiar una paleta de fondo, una paleta reservada para un sprite o colores preparados en RAM.

A diferencia de las macros de transferencia de PPU, también actualizan las copias de colores que necesita el juego y preparan el estado de los efectos. No hace falta copiar los buffers ni invalidar sus indicadores a mano.

'''Parámetros comunes'''

* <code>CGRAMOffset</code>: primer color que se cambiará, entre <code>$00</code> y <code>$FF</code>. Es un operando de 8 bits: <code>#$91</code> empieza en el color 1 de la paleta 9; <code>$00</code> utiliza el número guardado en esa scratch.
* <code>Length</code>: cantidad de bytes que se copiarán. Es un valor conocido al ensamblar, '''sin <code>#</code>''': <code>$001E</code> copia 15 colores. Debe ser mayor que cero y par, y la carga no debe pasar del último color de CGRAM.
* <code>GlobalEffect</code>: utiliza <code>0</code> para cargar sin efecto global o <code>1</code> para que la paleta reciba el efecto global. Es una opción fija de la llamada, no una variable de RAM.

'''Qué hace GlobalEffect'''

{| class="wikitable"
! Valor !! Comportamiento
|-
| <code>0</code> || Programa la transferencia de los colores sin efecto y actualiza los buffers de SMW y Dynamic Xtreme. Si los efectos están habilitados, excluye del efecto global las paletas modificadas.
|-
| <code>1</code> || Guarda los colores originales para que el sistema les aplique el efecto global antes de cargarlos. Registra las paletas modificadas para recibirlo y borra los indicadores de sus efectos anteriores.
|}

Con <code>GlobalEffect = 1</code> no se carga primero una versión sin efecto: se espera al resultado del sistema de efectos. Esto también sirve para dejar preparada una paleta cuando el ID del efecto global todavía es 0. Si los efectos de paleta están deshabilitados en la instalación, la llamada utiliza la carga directa.

Estas opciones afectan a cada paleta de 16 colores que toque la carga, no solo a los colores copiados. Para una carga con efecto global, proporciona todos los colores visibles de las paletas que cambies: por ejemplo, los 15 colores de una paleta de sprites, comenzando en su color 1. No uses una carga parcial para conservar otros colores originales que todavía no hayas preparado.

'''Entradas y resultado comunes'''

* Entra con A, X e Y en modo de 8 bits. D debe ser <code>$0000</code> en LoROM o <code>$3000</code> en el contexto habitual de SA-1 Pack. DBR debe permitir acceder al buffer de paletas de SMW: <code>$0703</code> en LoROM o su espejo <code>$6703</code> en SA-1. Los bancos habituales con espejos de RAM, como <code>$00-$3F</code> y <code>$80-$BF</code>, permiten esos accesos. Si pasas tablas con direcciones de 16 bits, DBR también debe permitir leerlas.
* Carry activado: la transferencia directa fue aceptada o los colores originales quedaron preparados para el efecto global. En este último caso, no significa que el resultado ya se haya cargado a pantalla.
* Carry desactivado: no se aceptó la transferencia directa por el límite de datos del frame. Puedes volver a intentarlo más adelante; no se actualizan los buffers ni los indicadores de efectos de esa carga.
* A y X pueden cambiar, tanto en éxito como en fallo. Y puede cambiar si se copian colores; no lo utilices para conservar otro dato entre llamadas. Los tres quedan en modo de 8 bits en ambos resultados. Conservan DBR y D.
* Las llamadas pueden modificar <code>$68-$6D</code> cuando están habilitados los efectos; las variantes <code>FromAddress</code>, <code>FromTable</code> y <code>Resource</code>, incluida <code>ResourceWithLength</code>, también utilizan <code>$65-$67</code>. No coloques el puntero de origen ni el color de destino en scratch que la propia llamada vaya a sobrescribir antes de terminar de utilizarlos.
* No incluyen <code>RTS</code> ni <code>RTL</code>: el código continúa después de la macro.

Si el origen está en RAM, conserva sus datos hasta que se ejecute la transferencia programada. El bloque de origen tampoco debe cruzar el final de su banco. Para <code>CGRAMOffset</code>, utiliza un inmediato o una variable que siga siendo válida después de que la macro cambie X e Y; evita operandos indexados con esos registros.

Llama a estas macros cuando quieras cambiar los colores, no en cada frame si la paleta sigue siendo la misma. Si utilizas una paleta de sprites con un destino fijo, resérvala para que la asignación automática no la utilice.

==== TransferPaletteFromAddress ====

<code>%TransferPaletteFromAddress()</code> carga colores desde una dirección conocida al ensamblar. Puede ser un label de tu código o un define con la dirección completa del recurso.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromAddress(Address, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Address</code>: dirección de origen completa, sin <code>#</code>.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; Paleta 9, colores 1-F, con efecto global.
%TransferPaletteFromAddress(!PaletteMyPalette, #$91, $001E, 1)
</pre>

<code>!PaletteMyPalette</code> se genera al instalar una paleta declarada en <code>Palettes</code> de un DynamicInfo y queda en <code>DXDefines.asm</code>. El nombre usa PascalCase: se eliminan espacios, guiones bajos y guiones, y se pone en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_palette</code> pasa a <code>MyPalette</code>.

==== TransferPaletteFromPointer ====

<code>%TransferPaletteFromPointer()</code> utiliza una dirección de origen que ya está guardada en tres bytes consecutivos de scratch. Es útil si tu código elige la paleta durante el juego.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromPointer(Pointer, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Pointer</code>: dirección del primer byte de la scratch, sin <code>#</code>. Los tres bytes deben contener la dirección de origen en orden bajo, alto y banco. Por ejemplo, <code>$02</code> utiliza <code>$02-$04</code>.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; Preparar la dirección de la paleta en $02-$04.
REP #$20
LDA.w #!PaletteMyPalette
STA $02
SEP #$20
LDA.b #!PaletteMyPalette>>16
STA $04

; Paleta 9, colores 1-F, sin efecto global.
%TransferPaletteFromPointer($02, #$91, $001E, 0)
</pre>

<code>!PaletteMyPalette</code> se genera desde una paleta del DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase eliminando separadores: <code>my_palette</code> se convierte en <code>MyPalette</code>.

==== TransferPaletteFromTable ====

<code>%TransferPaletteFromTable()</code> permite indicar por separado los dos bytes de dirección y el byte de banco del origen. Puedes obtenerlos de tablas, variables o valores inmediatos. La macro reúne esos datos en <code>$65-$67</code>.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteFromTable(TableAddr, TableBNK, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>TableAddr</code>: operando que se lee con A de 16 bits para obtener los dos bytes de dirección.
* <code>TableBNK</code>: operando que se lee con A de 8 bits para obtener el banco.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; $02-$03 contiene la dirección y $04 contiene el banco.
%TransferPaletteFromTable("$02", "$04", #$91, $001E, 1)
</pre>

A diferencia de <code>FromPointer</code>, los operandos de dirección y banco no tienen que estar en posiciones consecutivas. Si los lees desde tablas del código, el banco de datos debe permitir acceder a ellas.

==== TransferPaletteResource ====

<code>%TransferPaletteResource()</code> carga una paleta registrada en el DynamicInfo utilizando su tamaño completo. No necesitas escribir su dirección ni su cantidad de bytes.

'''Parámetros'''

<pre>
%TransferPaletteResource(Name, CGRAMOffset, GlobalEffect)
</pre>

* <code>Name</code>: nombre normalizado de la paleta, sin prefijo <code>!Palette</code> y sin extensión. La macro utiliza <code>!Palette<Name></code> y <code>!Palette<Name>Size</code>.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; MyPalette contiene 15 colores.
%TransferPaletteResource(MyPalette, #$91, 1)
BCS .Accepted
; No se aceptó la carga directa: volver a intentarlo después.
RTL
.Accepted
; Continuar con el resto del código.
</pre>

El ejemplo continúa en <code>.Accepted</code> si se aceptó la carga directa o se prepararon los colores para el efecto global. El <code>RTL</code> pertenece al ejemplo, no a la macro.

<code>MyPalette</code> corresponde a los defines <code>!PaletteMyPalette</code> y <code>!PaletteMyPaletteSize</code>, generados en <code>DXDefines.asm</code> desde la sección <code>Palettes</code> del DynamicInfo. El nombre usa PascalCase eliminando espacios, guiones bajos y guiones: <code>my_palette</code> pasa a <code>MyPalette</code>. Esta llamada no utiliza los defines <code>!Resource...</code> de la sección <code>Resources</code> ni las paletas convertidas RGB/HSL de un <code>*.paleffect</code>.

==== TransferPaletteResourceWithLength ====

<code>%TransferPaletteResourceWithLength()</code> utiliza la dirección de una paleta registrada, pero permite copiar solo la cantidad de bytes que indiques.

'''Parámetros'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferPaletteResourceWithLength(Name, CGRAMOffset, Length, GlobalEffect)
</pre>

* <code>Name</code>: nombre normalizado de la paleta, igual que en <code>%TransferPaletteResource()</code>.
* <code>Length</code>: cantidad de bytes que se copiarán, sin <code>#</code>. No debe superar el tamaño del recurso.
* Los demás parámetros y el carry funcionan como se explica en [[#Cargar colores con TransferPalette|Cargar colores con TransferPalette]].

'''Ejemplo'''

<pre>
; Copiar 4 colores al comienzo de la paleta 9, sin efecto global.
%TransferPaletteResourceWithLength(MyPalette, #$90, $0008, 0)
</pre>

<code>MyPalette</code> utiliza el define <code>!PaletteMyPalette</code>, generado desde una paleta del DynamicInfo y publicado en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_palette</code> se convierte en <code>MyPalette</code>.

<code>TransferPaletteCommon</code> y <code>TransferPaletteData</code> son las partes internas que comparten estas llamadas. Para cargar paletas desde tu código, utiliza las variantes anteriores, que también preparan el estado de los efectos.

=== Efectos de paleta ===

Estas macros permiten modificar los colores de una paleta: teñirla, cambiar su brillo, pasar de una paleta a otra o aplicar un efecto guardado en un archivo <code>*.paleffect</code>.

RGB trabaja con rojo, verde y azul. HSL trabaja con tono, saturación y luminosidad. Elige las macros RGB o HSL según el cambio que quieras realizar. Para conocer los efectos disponibles, consulta [[es/Dynamic_Xtreme_files_and_formats#Tipos_de_efectos|Tipos de efectos]].

'''¿Qué llamada necesitas?'''

{| class="wikitable"
! Quieres… !! Utiliza…
|-
| Teñir una paleta o cambiar su tono, saturación o luminosidad. || <code>Mix</code> / <code>MixAndMerge</code>.
|-
| Pasar de una paleta a otra. || <code>PaletteTransition</code>.
|-
| Aplicar un efecto que ya definiste en un archivo <code>*.paleffect</code>. || <code>DoEffect</code> / <code>DoEffectAndMerge</code>.
|-
| Darle un efecto propio a un sprite y conservar además el efecto global. || <code>ConcatenateRGBPaletteEffectToGlobal</code> o su variante HSL, después de asignar la paleta sin carga.
|}

Para calcular un efecto directamente, el proceso habitual es preparar los colores originales con <code>SetRGBBase</code> o <code>SetHSLBase</code> y después aplicar el cambio. Los ejemplos utilizan las variantes <code>Default</code>, que trabajan con las copias de paleta de Dynamic Xtreme y evitan escribir direcciones de memoria.

Las variantes <code>AndMerge</code> dejan los colores en el formato que necesita SNES para mostrarlos. Aun así, calcularlos no los envía automáticamente a la pantalla: la carga se completa mediante el manejo de paletas o las transferencias a CGRAM. Si estás usando las rutinas de concatenación después de <code>PaletteAssignmentNoUpload</code>, estas ya se encargan de preparar los colores y completar su carga.

En los ejemplos, prepara A en modo de 8 bits antes de llamar a las macros.

'''Registros y memoria temporal de los efectos'''

* Las macros de preparación de bases, mezcla, transición, conversión y <code>DoEffect</code> entran con A, X e Y de 8 bits. Sus variantes <code>Default</code> utilizan el mismo contrato. Las macros de concatenación tienen una entrada diferente, descrita en su apartado.
* Las macros anteriores preparan sus argumentos y llaman internamente a la rutina del parche. Al terminar continúan en la instrucción siguiente: no incluyen un retorno que termine tu rutina.
* A, X e Y deben tratarse como temporales y quedan en 8 bits al volver. No se devuelve éxito o fallo en carry: el resultado son los colores escritos en el buffer de destino. Conservan DBR y D conforme a las reglas de [[#Estado del CPU y memoria temporal|estado del CPU]].
* Pueden sobrescribir <code>$00-$0F</code>, <code>$45-$54</code>, <code>$6A</code>, <code>$8A-$8F</code> y <code>$D5-$D7</code>, según la operación. Allí se preparan punteros, longitudes, canales y ratios; no guardes en ese espacio valores que deban sobrevivir a la llamada.
* Los bancos de origen y destino se leen con A de 8 bits; las direcciones, offsets y cantidades de colores se leen con A de 16 bits durante la preparación. Los canales y ratios se leen con A de 8 bits. El ID de <code>DoEffect</code> se lee con A de 16 bits. Prepara los operandos de memoria con el tamaño correspondiente.
* Si tus operandos están indexados, X e Y deben identificar sus datos al entrar. Su valor puede cambiar dentro de la llamada. Las variantes completas también deben evitar que sus argumentos se solapen con los temporales que se preparan antes de leerlos.

==== Preparar los colores: SetRGBBase y SetHSLBase ====

Antes de modificar los colores, necesitas una copia con la que calcular el efecto. <code>%SetRGBBase()</code> prepara esa copia para efectos RGB; <code>%SetHSLBase()</code> la prepara para HSL. Si los colores originales no cambiaron, puedes reutilizarla en los siguientes frames.

En las variantes <code>Default</code> solo indicas el primer color y cuántos colores quieres preparar:

<pre>
%SetRGBBaseDefault(offset, length)
%SetHSLBaseDefault(offset, length)
</pre>

<code>offset</code> es el número del primer color y <code>length</code> es la cantidad. Por ejemplo, <code>#$0081</code> y <code>#$000F</code> seleccionan los 15 colores visibles de la paleta 8.

Si necesitas elegir tú las direcciones donde leer y guardar los colores, utiliza las versiones completas:

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%SetRGBBase(src, srcbnk, dst, dstbnk, offset, length)
%SetHSLBase(src, srcbnk, dst, dstbnk, offset, length)
</pre>

Las variantes <code>%SetRGBBaseDefault(offset, length)</code> y <code>%SetHSLBaseDefault(offset, length)</code> leen de <code>DX_PPU_CGRAM_PaletteCopy</code> y guardan el resultado en <code>DX_PPU_CGRAM_BaseRGBPalette</code> o <code>DX_PPU_CGRAM_BaseHSLPalette</code>.

'''Ejemplo: preparar una paleta de sprites'''

<pre>
; Paleta 8, sin incluir su primer color transparente.
%SetRGBBaseDefault(#$0081, #$000F)

; Para trabajar en HSL, utiliza esta variante en su lugar:
; %SetHSLBaseDefault(#$0081, #$000F)
</pre>

<code>$81</code> es el segundo color de la paleta 8: la paleta comienza en el color <code>$80</code> y se procesan los 15 siguientes.

==== Mezclar colores: Mix y MixAndMerge ====

Estas macros acercan los colores originales a los valores que indiques. Por ejemplo, puedes llevar el rojo a 31 y el verde y azul a 0 para teñir de rojo una paleta. Al cambiar poco a poco los ratios, el efecto aparece gradualmente.

Los parámetros <code>v</code> indican el color que quieres alcanzar, entre 0 y 31. Los parámetros <code>r</code> indican cuánto acercarse a ese color: 0 conserva el original, 127 aplica el cambio completo y 64 lo aplica aproximadamente a la mitad. En los ejemplos se escriben como <code>#$00</code>, <code>#$7F</code> y <code>#$40</code>.

Para RGB, los valores 1, 2 y 3 corresponden a rojo, verde y azul. Para HSL corresponden a tono, saturación y luminosidad.

El final del nombre indica qué componentes se modifican:

{| class="wikitable"
! RGB !! HSL !! Componentes modificados
|-
| <code>R</code>, <code>G</code>, <code>B</code> || <code>H</code>, <code>S</code>, <code>L</code> || Uno.
|-
| <code>RG</code>, <code>RB</code>, <code>GB</code> || <code>HS</code>, <code>HL</code>, <code>SL</code> || Dos.
|-
| <code>RGB</code> || <code>HSL</code> || Los tres.
|}

Cada combinación está disponible como <code>Mix...</code>, <code>MixAndMerge...</code> y <code>MixAndMerge...Default</code>. Por ejemplo: <code>%MixR()</code>, <code>%MixAndMergeR()</code> y <code>%MixAndMergeRDefault()</code>.

Primero se entregan los ratios de los componentes elegidos y después sus valores nuevos, en el orden del nombre. Al final van las direcciones de origen y destino, el primer color y la cantidad. Las variantes <code>Default</code> omiten las direcciones.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%MixRGB(r1, r2, r3, v1, v2, v3, src, srcbnk, dst, dstbnk, offset, length)
%MixAndMergeRG(r1, r2, v1, v2, src, srcbnk, dst, dstbnk, offset, length)
%MixAndMergeLDefault(r3, v3, offset, length)
</pre>

'''Ejemplo RGB: teñir de rojo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Preparar los colores originales de la paleta 8.
%SetRGBBaseDefault(#$0081, #$000F)

; Acercar los tres componentes a un rojo puro, aproximadamente a la mitad.
%MixAndMergeRGBDefault(#$40, #$40, #$40, #$1F, #$00, #$00, #$0081, #$000F)

</pre>

Los tres primeros valores <code>#$40</code> indican la intensidad del cambio para rojo, verde y azul. Los siguientes, <code>#$1F, #$00, #$00</code>, indican el rojo puro al que se acercarán. Los dos últimos seleccionan los 15 colores de la paleta 8.

'''Ejemplo HSL: aclarar la paleta'''

<pre>
%SetHSLBaseDefault(#$0081, #$000F)
%MixAndMergeLDefault(#$40, #$1F, #$0081, #$000F)
</pre>

Aquí solo cambia la luminosidad: <code>#$40</code> aplica aproximadamente la mitad del cambio y <code>#$1F</code> indica la luminosidad máxima. Este es un ejemplo independiente del anterior.

==== Cambiar entre paletas: PaletteTransition ====

Estas macros acercan cada color de la paleta original al color correspondiente de otra paleta. A diferencia de <code>Mix</code>, cada color tiene su propio destino. Sirven, por ejemplo, para pasar de los colores normales de un sprite a una paleta de daño.

Las variantes son <code>PaletteTransitionRGB</code>, <code>PaletteTransitionHSL</code>, <code>PaletteTransitionRGBAndMerge</code> y <code>PaletteTransitionHSLAndMerge</code>. Las dos variantes <code>AndMerge</code> también tienen versión <code>Default</code>.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%PaletteTransitionRGB(r1, r2, r3, src, srcbnk, targetpal, targetpalbnk, dst, dstbnk, offset, length)
%PaletteTransitionHSLAndMerge(r1, r2, r3, src, srcbnk, targetpal, targetpalbnk, dst, dstbnk, offset, length)
%PaletteTransitionRGBAndMergeDefault(r1, r2, r3, targetpal, targetpalbnk, offset, length)
</pre>

<code>targetpal</code> y <code>targetpalbnk</code> indican la dirección y el banco de la paleta de destino. Debe estar preparada con 3 bytes por color, en RGB o HSL según la macro. Los ratios controlan cuánto se acerca cada componente al color de destino.

'''Ejemplo: calcular un paso intermedio de una transición'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Este ejemplo trabaja con los primeros 15 colores de la copia de paletas.
%SetRGBBaseDefault(#$0000, #$000F)
%PaletteTransitionRGBAndMergeDefault(#$40, #$40, #$40, #!PaletteMyTargetRGB, #!PaletteMyTargetRGB>>16, #$0000, #$000F)
</pre>

El ejemplo supone que <code>!PaletteMyTargetRGB</code> corresponde a una paleta de destino RGB generada al instalar un <code>*.paleffect</code> de transición. Su dirección queda en <code>DXDefines.asm</code>. El nombre se normaliza eliminando espacios, guiones y guiones bajos y poniendo en mayúscula la inicial de cada palabra: <code>my_target</code> pasa a <code>MyTarget</code>. Para HSL se utiliza la paleta convertida a HSL y la macro correspondiente.

==== Aplicar un efecto de un archivo: DoEffect ====

<code>%DoEffect()</code> aplica un efecto de un archivo <code>*.paleffect</code> mediante su ID. El archivo ya contiene el tipo de efecto, los valores de color y los ratios, por lo que no necesitas entregarlos uno por uno.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%DoEffect(effect, src, srcbnk, dst, dstbnk, offset, length)
%DoEffectAndMerge(effect, src, srcbnk, dst, dstbnk, offset, length)
%DoEffectAndMergeDefaultRGB(effect, offset, length)
%DoEffectAndMergeDefaultHSL(effect, offset, length)
</pre>

* <code>effect</code>: ID del efecto, como <code>#!PaletteEffectIDMyEffect0</code>.
* El origen debe contener colores RGB o HSL separados, según el efecto elegido.
* <code>DoEffect</code> guarda el resultado con 3 bytes por color para poder seguir modificándolo.
* <code>DoEffectAndMerge</code> guarda colores en formato de SNES. Las variantes <code>DefaultRGB</code> y <code>DefaultHSL</code> eligen la base correspondiente y escriben en <code>DX_PPU_CGRAM_PaletteWriteMirror</code>.

'''Ejemplo: aplicar un efecto RGB a la paleta 8'''

<pre>
%SetRGBBaseDefault(#$0081, #$000F)
%DoEffectAndMergeDefaultRGB(#!PaletteEffectIDMyEffect0, #$81, #$000F)
</pre>

<code>!PaletteEffectIDMyEffect0</code> se genera desde un archivo <code>*.paleffect</code> y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_effect</code> pasa a <code>MyEffect</code>. El número final identifica el efecto dentro del archivo. Si el efecto trabaja en HSL, prepara la base HSL y utiliza <code>%DoEffectAndMergeDefaultHSL()</code>.

==== Convertir entre RGB y HSL ====

<code>%RGBToHSL()</code> convierte colores RGB a HSL y <code>%HSLToRGB()</code> hace el cambio contrario. Ambas leen y escriben 3 bytes por color. Sirven cuando necesitas continuar modificando una paleta con un efecto que usa el otro sistema de color.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%RGBToHSL(src, srcbnk, dst, dstbnk, offset, length)
%HSLToRGB(src, srcbnk, dst, dstbnk, offset, length)
</pre>

'''Ejemplo: convertir la base RGB a HSL'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%RGBToHSL(#DX_PPU_CGRAM_BaseRGBPalette, #DX_PPU_CGRAM_BaseRGBPalette>>16, #DX_PPU_CGRAM_BaseHSLPalette, #DX_PPU_CGRAM_BaseHSLPalette>>16, #$0081, #$000F)
</pre>

El ejemplo lee los 15 colores de la paleta 8 de la base RGB y guarda su equivalente en la base HSL. La base RGB debe estar preparada antes de llamar a la conversión.

==== Combinar un efecto propio con el global ====

'''Registros y memoria temporal:''' estas dos macros entran con A de 16 bits, X de 8 bits con el valor de la paleta y Y de 8 bits con el resultado de la asignación sin carga. Al volver los tres quedan en 8 bits. Con <code>sprite = 1</code>, X se recupera desde <code>!SpriteIndex</code>; con <code>sprite = 0</code>, no se conserva X. A e Y pueden cambiar. Utilizan los temporales de efectos y <code>$F0-$F3</code>. Conservan DBR y D. A diferencia de las demás macros de efectos, incluyen <code>RTL</code> y devuelven disponibilidad mediante carry, también cuando reutilizan un resultado anterior.

<code>%ConcatenateRGBPaletteEffectToGlobal()</code> y <code>%ConcatenateHSLPaletteEffectToGlobal()</code> permiten aplicar un efecto propio a una paleta que también debe recibir el efecto global. Son las macros utilizadas por las llamadas para sprites del mismo nombre, pero permiten elegir las variables de paleta.

Suelen utilizarse después de <code>%PaletteAssignmentNoUpload()</code> o su variante para sprites: primero se asigna la paleta sin cargar los colores y después se aplican los efectos. Conserva los datos devueltos por la asignación para esta segunda llamada.

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%ConcatenateRGBPaletteEffectToGlobal(sprite, paletteOption, palette)
%ConcatenateHSLPaletteEffectToGlobal(sprite, paletteOption, palette)
</pre>

* <code>sprite</code>: 1 recupera el índice del sprite desde <code>!SpriteIndex</code>; 0 permite utilizar variables propias.
* <code>paletteOption</code>: variable o valor de las opciones de paleta; activa el bit <code>$80</code> para incluir el efecto global.
* <code>palette</code>: variable que contiene la paleta asignada, entre <code>$00</code> y <code>$0E</code> de dos en dos.
* A de 16 bits: ID del efecto local RGB o HSL, según la macro.
* X de 8 bits: copia del valor de la paleta asignada.
* Y de 8 bits: conserva el valor devuelto por la asignación sin carga.
* <code>$02-$04</code>: dirección de los colores originales preparada por esa asignación.

Devuelven el carry activado si se puede dibujar con el efecto solicitado o con el anterior mientras se prepara el nuevo. Si todavía no hay un resultado disponible, el carry queda desactivado. Estas dos macros ya terminan la rutina con <code>RTL</code>.

'''Ejemplo: completar una asignación sin carga'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
; Llamar esta rutina con JSL después de asignar la paleta sin carga.
; Deben conservarse Y y $02-$04 de aquella llamada.
ApplyLocalEffect:
LDA !NormalPalette,x
TAX
REP #$20
LDA #!PaletteEffectIDMyEffect0
%ConcatenateRGBPaletteEffectToGlobal(1, "!NormalPaletteOption,x", "!NormalPalette,x")
</pre>

<code>!PaletteEffectIDMyEffect0</code> se genera desde un <code>*.paleffect</code> y queda en <code>DXDefines.asm</code>. El nombre se normaliza en PascalCase eliminando separadores: <code>my_effect</code> pasa a <code>MyEffect</code>. Para un efecto HSL, utiliza la macro HSL. Si usas Y para leer una tabla de efectos, guarda su valor con <code>PHY</code> y recupéralo con <code>PLY</code> antes de concatenar.

==== Elegir las direcciones y combinar varios efectos ====

Las variantes <code>Default</code> de los ejemplos eligen las direcciones por ti. Si necesitas guardar los resultados en otro lugar o aplicar varios efectos seguidos, utiliza las versiones completas. Estos son los parámetros de dirección que aparecen en ellas:

* <code>src</code>: dónde leer los colores originales; <code>srcbnk</code>: su banco.
* <code>dst</code>: dónde guardar el resultado; <code>dstbnk</code>: su banco. El destino debe ser un espacio de RAM que tu código pueda utilizar.
* <code>offset</code>: primer color que se procesará, contando desde 0.
* <code>length</code>: cantidad de colores que se procesarán.

Para indicar una dirección fija, se utiliza <code>#Nombre</code> para la dirección y <code>#Nombre>>16</code> para su banco, como en el ejemplo de conversión RGB a HSL. También puedes pasar variables que contengan esos datos.

El espacio necesario depende del paso que estés realizando:

{| class="wikitable"
! Operación !! Lee !! Guarda
|-
| <code>SetRGBBase</code> / <code>SetHSLBase</code> || Paleta normal: 2 bytes por color. || Colores separados: 3 bytes por color.
|-
| <code>Mix</code>, <code>PaletteTransition</code>, <code>DoEffect</code> sin <code>AndMerge</code> || Colores separados: 3 bytes por color. || Colores separados: 3 bytes por color.
|-
| Variantes <code>AndMerge</code> || Colores separados: 3 bytes por color. || Paleta normal: 2 bytes por color.
|-
| <code>RGBToHSL</code> / <code>HSLToRGB</code> || Colores separados: 3 bytes por color. || Colores separados: 3 bytes por color.
|}

Por ejemplo, si quieres aplicar dos efectos seguidos, el primero debe guardar sus colores separados, sin <code>AndMerge</code>. El segundo lee ese resultado y utiliza <code>AndMerge</code> para dejar la paleta lista para cargarla. Si uno trabaja en RGB y el otro en HSL, convierte los colores entre ambos pasos.

Las macros utilizan memoria temporal, entre otras las direcciones <code>$45-$50</code>, <code>$51-$53</code>, <code>$6A</code>, <code>$8A</code>, <code>$8C</code>, <code>$8E</code>, <code>$0E-$0F</code> y <code>$D5-$D7</code>, según la operación. No guardes en ellas datos que necesites conservar después de la llamada.

=== PPU ===

Estas macros permiten cargar gráficos en VRAM y colores en CGRAM. VRAM es la memoria donde SNES guarda los gráficos que muestra; CGRAM guarda sus paletas.

La llamada deja anotada una transferencia para el próximo NMI, cuando el juego puede actualizar esas memorias. No hace la copia inmediatamente. Los datos de origen deben seguir disponibles hasta que se realice la transferencia.

'''Qué llamada elegir'''

{| class="wikitable"
! Necesitas… !! VRAM !! CGRAM
|-
| Indicar la dirección de origen y su banco por separado. || <code>TransferToVRAM</code> || <code>TransferToCGRAM</code>
|-
| Indicar una dirección completa y dejar que la macro obtenga el banco. || <code>TransferToVRAMFromAddr</code> || <code>TransferToCGRAMFromAddr</code>
|-
| Cargar un recurso completo registrado en Dynamic Xtreme. || <code>TransferResourceToVRAM</code> || <code>TransferResourceToCGRAM</code>
|-
| Cargar solo una cantidad de bytes de un recurso. || <code>TransferResourceToVRAMWithLenght</code> || <code>TransferResourceToCGRAMWithLenght</code>
|}

Las versiones normales comprueban si la transferencia cabe dentro del límite de bytes del frame:

* Carry activado: la transferencia quedó programada.
* Carry desactivado: no se programó porque superaría ese límite. Tu código puede intentarlo en otro frame.

Este límite se comparte con las demás cargas de Dynamic Xtreme. Programar varias copias en un frame consume parte del mismo límite. Estas macros modifican A y X. Al aceptar la transferencia dejan A, X e Y en modo de 8 bits; si la rechazan, dejan A en 8 bits, pero no cambian necesariamente el modo de X e Y.

'''Registros y memoria temporal de las transferencias'''

* Entra con A, X e Y en 8 bits. Las versiones normales establecen internamente A de 16 bits para comprobar el presupuesto, pero este estado de entrada también permite utilizar las variantes <code>Forced</code>, especialmente las de CGRAM.
* Al aceptar la transferencia, A y X cambian y los tres registros quedan en 8 bits. Y no se utiliza como registro de trabajo, pero pierde su byte alto si entrabas con índices de 16 bits. Al rechazarla, A cambia y queda en 8 bits; X e Y conservan sus valores y el tamaño que tenían al entrar.
* No utilizan scratch para preparar la solicitud. Escriben en las listas de transferencias y en el contador de bytes del frame. Conservan DBR y D. DBR debe permitir acceder al contador; las variantes también pueden necesitar ese banco para leer los operandos de memoria que tú entregues.
* Las direcciones de origen y las longitudes se leen con A de 16 bits. El destino de VRAM y su argumento de banco se leen con A de 16 bits; el banco debe proporcionarse como un valor de 16 bits cuyo byte alto sea cero. En CGRAM, el banco de origen y el color de destino se leen con A de 8 bits.
* X cambia antes de leer varios argumentos. No pases direcciones indexadas con X suponiendo que conservará el índice del sprite. Prefiere inmediatos o variables independientes de X para los datos de la transferencia.
* No incluyen <code>RTS</code> ni <code>RTL</code>. El código continúa después de la expansión. Comprueba el carry de las variantes normales antes de otra operación que lo modifique. Las variantes <code>Forced</code> no devuelven un indicador de éxito en carry.

Estas reglas también se aplican a las variantes <code>FromAddr</code>, <code>Resource</code> y <code>WithLenght</code>: preparan los argumentos y expanden la misma transferencia.

==== TransferToVRAM ====

<code>%TransferToVRAM()</code> programa una copia de gráficos desde ROM o RAM hacia VRAM.

<pre>
%TransferToVRAM(VRAMOffset, ResourceAddr, ResourceBNK, Lenght)
</pre>

* <code>VRAMOffset</code>: dirección de destino en VRAM, expresada en palabras de 2 bytes. Por ejemplo, copiar <code>$0200</code> bytes desde <code>$6000</code> ocupa las palabras <code>$6000-$60FF</code>.
* <code>ResourceAddr</code>: dirección de origen dentro de su banco.
* <code>ResourceBNK</code>: banco del origen.
* <code>Lenght</code>: cantidad de bytes que se copiarán. Se conserva esta escritura del nombre porque así aparece en la macro.

'''Ejemplo: programar la carga de gráficos'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToVRAM(#$6000, #!ResourceMyGraphics, #!ResourceMyGraphics>>16, #$0200)
BCC .NotLoaded
; La copia se realizará en el próximo NMI.
.NotLoaded
</pre>

<code>!ResourceMyGraphics</code> es la dirección de un recurso registrado desde un DynamicInfo; queda en <code>DXDefines.asm</code>. El nombre se normaliza eliminando espacios, guiones y guiones bajos y poniendo en mayúscula la inicial de cada palabra: <code>my_graphics</code> pasa a <code>MyGraphics</code>. La cantidad de bytes solicitada debe existir en ese recurso.

==== TransferToVRAMFromAddr ====

Hace la misma copia, pero recibe la dirección completa del origen. La macro separa su dirección y banco por ti.

<pre>
%TransferToVRAMFromAddr(VRAMOffset, addr, Lenght)
</pre>

<code>addr</code> se escribe sin <code>#</code>; los otros parámetros se entregan como en <code>TransferToVRAM</code>.

'''Ejemplo'''

<pre>
%TransferToVRAMFromAddr(#$6000, !ResourceMyGraphics, #$0200)
BCC .NotLoaded
.NotLoaded
</pre>

<code>!ResourceMyGraphics</code> se genera desde un recurso del DynamicInfo y queda en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase: <code>my_graphics</code> se convierte en <code>MyGraphics</code>.

==== TransferResourceToVRAM y TransferResourceToVRAMWithLenght ====

Estas variantes reciben el nombre de un recurso de Dynamic Xtreme. La primera copia el recurso completo; la segunda copia la cantidad de bytes que indiques.

<pre>
%TransferResourceToVRAM(VRAMOffset, ResourceName)
%TransferResourceToVRAMWithLenght(VRAMOffset, ResourceName, Lenght)
</pre>

Para un recurso cuyos defines sean <code>!ResourceMyGraphics</code> y <code>!ResourceMyGraphicsSize</code>, escribe <code>"MyGraphics"</code> como <code>ResourceName</code>.

'''Ejemplo: cargar el recurso completo'''

<pre>
%TransferResourceToVRAM(#$6000, "MyGraphics")
BCC .NotLoaded
.NotLoaded
</pre>

'''Ejemplo: cargar solo sus primeros $0200 bytes'''

<pre>
%TransferResourceToVRAMWithLenght(#$6000, "MyGraphics", #$0200)
BCC .NotLoaded
.NotLoaded
</pre>

El nombre y el tamaño se obtienen de los defines generados en <code>DXDefines.asm</code> al instalar los recursos del DynamicInfo. Utiliza el nombre normalizado: <code>my_graphics</code> pasa a <code>MyGraphics</code>, eliminando los separadores y poniendo en mayúscula la inicial de cada palabra.

==== TransferToCGRAM ====

<code>%TransferToCGRAM()</code> programa una copia de colores desde ROM o RAM hacia una paleta de SNES.

<pre>
%TransferToCGRAM(CGRAMOffset, TableAddr, TableBNK, Lenght)
</pre>

* <code>CGRAMOffset</code>: número del primer color de destino, entre <code>$00</code> y <code>$FF</code>. Por ejemplo, la paleta 8 comienza en el color <code>$80</code>.
* <code>TableAddr</code> y <code>TableBNK</code>: dirección y banco de los colores que se van a copiar.
* <code>Lenght</code>: cantidad de bytes. Cada color ocupa 2 bytes; 15 colores ocupan <code>$001E</code> bytes.

Los colores de origen deben estar en formato normal de SNES, BGR555. Si calculaste un efecto, utiliza su resultado final de 2 bytes por color, como el que producen las variantes <code>AndMerge</code>.

'''Ejemplo: copiar los 15 colores visibles de la paleta 8'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToCGRAM(#$81, #DX_PPU_CGRAM_PaletteWriteMirror+$0102, #DX_PPU_CGRAM_PaletteWriteMirror>>16, #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

Este ejemplo toma el resultado de un efecto guardado en <code>DX_PPU_CGRAM_PaletteWriteMirror</code>. El desplazamiento <code>$0102</code> corresponde al color <code>$81</code>, porque cada color ocupa 2 bytes. Se omite el primer color de la paleta, que es transparente en sprites.

==== TransferToCGRAMFromAddr ====

Hace la misma copia de colores, pero recibe la dirección completa del origen. Escribe <code>addr</code> sin <code>#</code>.

<pre>
%TransferToCGRAMFromAddr(CGRAMOffset, addr, Lenght)
</pre>

'''Ejemplo'''

<pre style="white-space: pre-wrap; overflow-wrap: anywhere;">
%TransferToCGRAMFromAddr(#$81, DX_PPU_CGRAM_PaletteWriteMirror+$0102, #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

El resultado es el mismo que en el ejemplo anterior: programa la carga de 15 colores a partir del segundo color de la paleta 8.

==== TransferResourceToCGRAM y TransferResourceToCGRAMWithLenght ====

Estas variantes copian los colores de un recurso registrado en Dynamic Xtreme. La primera utiliza su tamaño completo; la segunda utiliza la cantidad de bytes que indiques.

<pre>
%TransferResourceToCGRAM(CGRAMOffset, ResourceName)
%TransferResourceToCGRAMWithLenght(CGRAMOffset, ResourceName, Lenght)
</pre>

'''Ejemplo: copiar un recurso completo de colores'''

<pre>
%TransferResourceToCGRAM(#$80, "MyColors")
BCC .NotLoaded
.NotLoaded
</pre>

'''Ejemplo: copiar solo 15 colores'''

<pre>
%TransferResourceToCGRAMWithLenght(#$81, "MyColors", #$001E)
BCC .NotLoaded
.NotLoaded
</pre>

Estos ejemplos suponen un recurso general de colores con los defines <code>!ResourceMyColors</code> y <code>!ResourceMyColorsSize</code>, generados en <code>DXDefines.asm</code> desde un DynamicInfo. Utiliza el nombre normalizado: <code>my_colors</code> pasa a <code>MyColors</code>. En el segundo ejemplo, el recurso debe comenzar con los 15 colores que se quieren copiar, sin anteponer el color transparente.

==== Variantes Forced ====

Todas las transferencias anteriores tienen una variante cuyo nombre comienza con <code>Forced</code>. Programa la copia aunque supere el límite de bytes del frame. La cantidad copiada también se suma al total de ese frame.

{| class="wikitable"
! VRAM !! CGRAM
|-
| <code>ForcedTransferToVRAM</code> || <code>ForcedTransferToCGRAM</code>
|-
| <code>ForcedTransferToVRAMFromAddr</code> || <code>ForcedTransferToCGRAMFromAddr</code>
|-
| <code>ForcedTransferResourceToVRAM</code> || <code>ForcedTransferResourceToCGRAM</code>
|-
| <code>ForcedTransferResourceToVRAMWithLenght</code> || <code>ForcedTransferResourceToCGRAMWithLenght</code>
|}

Reciben los mismos parámetros que las versiones sin <code>Forced</code>. Su carry no indica si la transferencia fue aceptada. Prepara A en modo de 8 bits antes de utilizarlas; al terminar dejan A, X e Y en modo de 8 bits.

'''Ejemplo'''

<pre>
%ForcedTransferResourceToVRAM(#$6000, "MyGraphics")
; No se comprueba el carry en esta variante.
</pre>

<code>MyGraphics</code> corresponde al recurso <code>!ResourceMyGraphics</code> de <code>DXDefines.asm</code>, generado desde el DynamicInfo. Se utiliza el nombre normalizado, como <code>my_graphics</code> → <code>MyGraphics</code>.

Utiliza <code>Forced</code> para cargas que deben tener prioridad y cuyo tamaño ya controlas. Si fuerzas demasiados datos, las copias pueden superar el tiempo disponible para actualizar los gráficos. En las demás cargas, utiliza las variantes normales y comprueba el carry.

=== Matemáticas ===

Estas macros multiplican y dividen números utilizando el hardware de SNES o SA-1, según la ROM. Utilizan números sin signo: los valores representan cantidades positivas o cero.

Prepara A en modo de 8 bits antes de llamarlas. Las macros no cambian por ti el tamaño de A, X o Y.

'''Registros y memoria temporal:''' todas las macros de esta categoría, incluidas <code>W</code> y <code>After...</code>, modifican A y N/Z, conservan X, Y, carry, DBR y D, y no utilizan scratch. Mantienen el tamaño de los registros con el que entraron; A debe estar en 8 bits para que las escrituras al hardware sean correctas. DBR debe permitir acceder a los registros aritméticos de SNES o SA-1, según corresponda. No incluyen <code>RTS</code> ni <code>RTL</code>; el código continúa después de la macro. El resultado está en los registros hardware indicados abajo, no en A. El carry no informa de éxito ni de desbordamiento del cálculo.

'''Cómo escribir los argumentos'''

<code>Mul</code>, <code>Div</code>, <code>MulAfterMul</code> y <code>DivAfterDiv</code> pegan el argumento directamente después de <code>LDA</code>. Escribe el argumento entre comillas con un espacio al principio: <code>" #$05"</code> produce <code>LDA #$05</code>.

También puedes comenzar el argumento con <code>.b</code>, <code>.w</code> o <code>.l</code> para elegir cómo se escribe el acceso a memoria. Por ejemplo, si <code>$02</code> contiene el número que quieres multiplicar:

<pre>
%Mul(".b $02", " #$07")
</pre>

Esto genera <code>LDA.b $02</code> para leer el primer número y <code>LDA #$07</code> para el segundo. Los sufijos eligen cómo se accede a la dirección; no cambian cuántos bits tiene A. La multiplicación sigue utilizando números de 8 bits.

Las variantes con <code>W</code>, además de <code>MulAfterDiv</code> y <code>DivAfterMul</code>, ya añaden un espacio antes de los argumentos. En ellas puedes escribir los valores normalmente, como <code>%MulW(#$05, #$07)</code>. En la implementación actual no se pasan los sufijos <code>.b</code>, <code>.w</code> o <code>.l</code> de esta misma manera a esas variantes, porque el espacio que añaden quedaría entre <code>LDA</code> y el sufijo.

'''¿Qué significa la W?'''

El hardware necesita un pequeño tiempo para terminar el cálculo. Las macros con <code>W</code> incluyen esa espera: puedes leer el resultado inmediatamente después. Las versiones sin <code>W</code> permiten ejecutar otro código mientras se calcula, pero debes dejar pasar el tiempo necesario antes de leerlo. Si necesitas el resultado en la siguiente instrucción, utiliza la variante con <code>W</code>.

Los resultados se leen mediante estos defines:

* <code>!MultiplicationResult</code>: resultado de multiplicar, de 16 bits.
* <code>!DivisionResult</code>: cociente de la división, de 16 bits.
* <code>!RemainderResult</code>: resto de la división, de 16 bits.

Estos defines ya seleccionan la dirección correspondiente a SNES o SA-1. El siguiente cálculo puede cambiar los resultados anteriores; guárdalos si los necesitas después.

==== Mul y MulW ====

Multiplican dos valores de 8 bits y producen un resultado de 16 bits.

<pre>
%Mul(a, b)
%MulW(a, b)
</pre>

<code>a</code> y <code>b</code> pueden ser valores inmediatos, como <code>#$06</code>, o variables de 8 bits.

'''Ejemplo: 6 × 7 = 42'''

<pre>
%MulW(#$06, #$07)
REP #$20
LDA !MultiplicationResult ; A = $002A, es decir, 42
SEP #$20
</pre>

La llamada sin espera sería <code>%Mul(" #$06", " #$07")</code>. En ese caso no leas el resultado inmediatamente: ejecuta antes otro código que no utilice el hardware de multiplicación o división.

==== Div y DivW ====

Dividen un número de 16 bits por uno de 8 bits. El número de 16 bits se entrega separado en dos bytes: primero el alto y después el bajo.

<pre>
%Div(ah, al, b)
%DivW(ah, al, b)
</pre>

* <code>ah</code>: byte alto del número que quieres dividir.
* <code>al</code>: byte bajo del mismo número.
* <code>b</code>: número por el que divides, entre 1 y 255.

'''Ejemplo: 300 ÷ 7 = 42, con resto 6'''

<pre>
; 300 = $012C: byte alto $01, byte bajo $2C.
%DivW(#$01, #$2C, #$07)

REP #$20
LDA !DivisionResult ; A = $002A, es decir, 42
LDA !RemainderResult ; A = $0006
SEP #$20
</pre>

También puedes pasar una variable de 16 bits como dos argumentos: <code>%DivW(MiNumero+1, MiNumero, #$07)</code>. <code>MiNumero</code> representa aquí una variable definida por tu código.

==== Continuar desde el resultado anterior ====

Las variantes <code>AfterMul</code> y <code>AfterDiv</code> toman el resultado del cálculo anterior como primer número. Solo debes indicar el segundo número.

{| class="wikitable"
! Macro !! Cálculo que realiza
|-
| <code>MulAfterMul(b)</code> / <code>MulWAfterMul(b)</code> || Toma los 8 bits bajos del resultado de la multiplicación anterior y los multiplica por b.
|-
| <code>MulAfterDiv(b)</code> / <code>MulWAfterDiv(b)</code> || Toma los 8 bits bajos del cociente anterior y los multiplica por b.
|-
| <code>DivAfterMul(b)</code> / <code>DivWAfterMul(b)</code> || Divide el resultado completo de la multiplicación anterior por b.
|-
| <code>DivAfterDiv(b)</code> / <code>DivWAfterDiv(b)</code> || Divide el cociente completo de la división anterior por b.
|}

La W sigue indicando que puedes leer el nuevo resultado inmediatamente después. Las variantes <code>After...</code> ya incluyen la espera que necesitan para tomar el resultado del cálculo anterior.

'''Ejemplo: dos multiplicaciones, (6 × 7) × 2 = 84'''

<pre>
%Mul(" #$06", " #$07")
%MulWAfterMul(#$02)
REP #$20
LDA !MultiplicationResult ; A = $0054, es decir, 84
SEP #$20
</pre>

'''Ejemplo: dividir y después multiplicar, (100 ÷ 4) × 3 = 75'''

<pre>
%Div(" #$00", " #$64", " #$04")
%MulWAfterDiv(#$03)
REP #$20
LDA !MultiplicationResult ; A = $004B, es decir, 75
SEP #$20
</pre>

'''Ejemplo: multiplicar y después dividir, (20 × 15) ÷ 4 = 75'''

<pre>
%Mul(" #$14", " #$0F")
%DivWAfterMul(#$04)
REP #$20
LDA !DivisionResult ; A = $004B, es decir, 75
SEP #$20
</pre>

'''Ejemplo: dos divisiones, (300 ÷ 3) ÷ 4 = 25'''

<pre>
%Div(" #$01", " #$2C", " #$03")
%DivWAfterDiv(#$04)
REP #$20
LDA !DivisionResult ; A = $0019, es decir, 25
SEP #$20
</pre>

En las multiplicaciones, el primer número siempre se limita a 8 bits. Si el resultado anterior era mayor que 255, <code>MulAfterMul</code> o <code>MulAfterDiv</code> solo utilizará su byte bajo. Las divisiones de esta tabla sí toman el resultado anterior completo, de 16 bits.

es/Dynamic Xtreme Quick Start

2026-10-25T17:15:30Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_Quick_Start}}

Esta guía explica cómo realizar una instalación básica de Dynamic
Xtreme en Windows o Linux.

Si es la primera vez que utilizas la herramienta, sigue los pasos en
el orden indicado. No es necesario conocer el funcionamiento interno
del sistema para completar la instalación.

== Requisitos ==

Dynamic Xtreme requiere el runtime de .NET 8. Descarga e instala la
versión correspondiente a tu sistema operativo desde el sitio oficial
de Microsoft:

[https://dotnet.microsoft.com/download/dotnet/8.0 .NET 8 Runtime]

La herramienta es compatible con Windows y Linux. Solo necesitas el
runtime de .NET; no es necesario instalar el SDK completo.

Puedes descargar Dynamic Xtreme desde SNEStorage: [https://snestorage.dev/Resource/7 SNEStorage - Dynamic Xtreme]

== Preparar los recursos ==

Antes de ejecutar Dynamic Xtreme, añade a tu proyecto todos los
recursos que deseas instalar.

=== Recursos para PIXI y UberASMTool ===

Los recursos actuales normalmente incluyen su archivo
<code>*.asm</code> o <code>*.json</code> junto con los archivos que
necesitan. Copia el paquete completo sin cambiar su estructura de
carpetas.

En PIXI, utiliza la carpeta correspondiente al tipo de sprite:

* <code>sprites</code> para sprites normales.
* <code>cluster</code> para cluster sprites.
* <code>extended</code> para extended sprites.
* Para otros tipos, utiliza la carpeta indicada por el recurso.

En UberASMTool, utiliza la carpeta correspondiente al tipo de código:

* <code>level</code> para códigos de nivel.
* <code>overworld</code> para códigos del overworld.
* <code>gamemode</code> para códigos de game mode.
* Para otros tipos, utiliza la carpeta indicada por el recurso.

Después de copiar el recurso, añádelo al archivo de lista de PIXI o
UberASMTool como lo harías normalmente.

Los recursos preparados para Dynamic Xtreme ya contienen las
declaraciones necesarias en su archivo ASM principal. Mantén juntos
el ASM, el JSON y las carpetas incluidas con el recurso para no romper
sus rutas relativas.

=== Carpetas tradicionales ===

Algunos recursos utilizan las carpetas tradicionales de Dynamic
Xtreme. En ese caso, sigue esta organización:

Estas carpetas se encuentran junto al ejecutable de Dynamic Xtreme: <code>dxt.exe</code> en Windows o <code>dxt</code> en Linux.

{| class="wikitable"
! Tipo de archivo
! Carpeta
|-
| <code>*.dynamicinfo</code>
| <code>DynamicInfos</code>
|-
| <code>*.drawinfo</code>
| <code>DrawInfos</code>
|-
| <code>*.paleffect</code>
| <code>PaletteEffects</code>
|-
| Gráficos, paletas y otros archivos relacionados
| <code>DynamicResources</code>
|}

Utiliza siempre el método indicado por el recurso. No muevas a las
carpetas tradicionales los archivos de un sprite o código UberASM
moderno, salvo que sus instrucciones lo soliciten.

== Instalación completa ==

=== Ejecutar la herramienta ===

Dynamic Xtreme debe ejecutarse desde su propia carpeta.

* En Windows, haz doble clic en <code>dxt.exe</code>.
* En Linux, abre una terminal en la carpeta de Dynamic Xtreme y ejecuta:

<pre>
./dxt
</pre>

La herramienta mostrará una serie de preguntas para configurar la
instalación.

=== Configurar las rutas ===

Las rutas y las funcionalidades seleccionadas quedan guardadas en <code>Settings/Settings.json</code>, dentro de la carpeta de Dynamic Xtreme. La herramienta utiliza ese archivo para recuperar la configuración en las siguientes instalaciones.

Puedes escribir cada ruta o arrastrar el archivo correspondiente a la
terminal. Después, presiona Enter para continuar.

Si dejas una respuesta vacía y presionas Enter, Dynamic Xtreme
utilizará el valor guardado en <code>Settings/Settings.json</code>. Si todavía no
existe un valor guardado y la ruta es opcional, esa integración se
omitirá.

Las rutas se solicitan en el siguiente orden:

# '''ROM de entrada'''
#: Selecciona la ROM de Super Mario World que deseas modificar.

# '''ROM de salida'''
#: Indica la ruta de la ROM que tendrá el resultado de la instalación.

# '''Ejecutable de PIXI'''
#: Selecciona el ejecutable de PIXI. Esta ruta permite integrar las
#: rutinas y definiciones de Dynamic Xtreme con PIXI.

# '''Ejecutable de UberASMTool'''
#: Selecciona el ejecutable de UberASMTool si tu proyecto utiliza
#: códigos de UberASM.

# '''Ejecutable de GPS'''
#: Selecciona el ejecutable de GPS si tu proyecto utiliza bloques
#: personalizados.

# '''Lista de PIXI'''
#: Selecciona el archivo de lista donde registraste los sprites que
#: utilizará tu proyecto.

# '''Lista de UberASMTool'''
#: Selecciona el archivo de lista donde registraste los códigos
#: UberASM que utilizará tu proyecto.

Las rutas de PIXI, UberASMTool, GPS y sus listas son opcionales.
Si no utilizas alguna de estas herramientas y no existe una ruta
guardada, puedes dejar la respuesta vacía.

Para dejar de utilizar una integración que ya tiene rutas guardadas, edita <code>Settings/Settings.json</code> y deja sus valores como cadenas vacías (<code>""</code>):

* PIXI: <code>PixiPath</code> y <code>PixiListPath</code>.
* UberASMTool: <code>UberasmToolPath</code> y <code>UberasmListPath</code>.
* GPS: <code>GPSPath</code>.

No elimines los campos ni reemplaces todo el archivo. En las siguientes preguntas podrás dejar esas rutas vacías sin recuperar la integración anterior.

=== Seleccionar las funciones ===

Después de configurar las rutas, Dynamic Xtreme preguntará qué
funciones deseas instalar.

Puedes responder <code>Y</code> para habilitar una función o
<code>N</code> para deshabilitarla.

Si presionas Enter sin escribir nada, se conservará el valor guardado
en <code>Settings/Settings.json</code>. Durante la primera instalación se utilizará
el valor predeterminado de la función.

En una instalación habitual se pueden habilitar las funciones que no
muestran advertencias. Si aparece una advertencia en rojo, léela con
atención y comprueba su compatibilidad con tu proyecto antes de
habilitar esa función.

Consulta [[es/Dynamic_Xtreme#Funcionalidades|Funcionalidades]] para saber qué hace cada opción y [[es/Dynamic_Xtreme#Compatibilidad|Compatibilidad]] para revisar los posibles conflictos con otros recursos y los espacios de RAM utilizados.

=== Ejemplo de instalación típica con PIXI y UberASMTool ===

Este ejemplo utiliza PIXI y UberASMTool con las opciones predeterminadas. Las rutas son ficticias y corresponden a Windows; sustitúyelas por las de tu proyecto. En Linux, indica las rutas de sus ejecutables correspondientes.

{| class="wikitable"
! Pregunta !! Ejemplo de respuesta
|-
| ROM de entrada || <code>C:\MiHack\MiHack.smc</code>
|-
| ROM de salida || <code>C:\MiHack\MiHack_DX.smc</code>
|-
| Ejecutable de PIXI || <code>C:\MiHack\PIXI\pixi.exe</code>
|-
| Ejecutable de UberASMTool || <code>C:\MiHack\UberASMTool\UberASMTool.exe</code>
|-
| Ejecutable de GPS || Dejar vacío si no se utiliza y no hay una ruta guardada.
|-
| Lista de PIXI || <code>C:\MiHack\PIXI\list.txt</code>
|-
| Lista de UberASMTool || <code>C:\MiHack\UberASMTool\list.txt</code>
|}

Para las funcionalidades, utiliza estos valores:

{| class="wikitable"
! Funcionalidad !! Activada !! Respuesta
|-
| <code>GraphicsChange</code> || Sí || <code>Y</code>
|-
| <code>PalettesChange</code> || Sí || <code>Y</code>
|-
| <code>DynamicPoses</code> || Sí || <code>Y</code>
|-
| <code>DrawingSystem</code> || Sí || <code>Y</code>
|-
| <code>PalettesEffects</code> || Sí || <code>Y</code>
|-
| <code>Free7E2000</code> || Sí || <code>Y</code>
|-
| <code>ControllerOptimization</code> || Sí || <code>Y</code>
|-
| <code>FixedColorOptimization</code> || Sí || <code>Y</code>
|-
| <code>KevinLMVRAMOptimization</code> || No || <code>N</code>
|-
| <code>StatusBarOptimization</code> || No || <code>N</code>
|-
| <code>PlayerFeatures</code> || No || <code>N</code>
|-
| <code>YoshiFeatures</code> || No || <code>N</code>
|}

En ROMs con SA-1, <code>Free7E2000</code> se desactiva automáticamente.

Enter conserva el valor guardado si ya utilizaste la herramienta. Para reproducir esta configuración, responde <code>Y</code> o <code>N</code> según la tabla; los valores predeterminados solo se utilizan cuando no hay una selección anterior.

== Instalación mediante línea de comandos ==

Después de completar una instalación interactiva, Dynamic Xtreme
guarda las rutas y funciones seleccionadas en
<code>Settings/Settings.json</code>.

Puedes reutilizar esa configuración para realizar instalaciones
posteriores sin responder nuevamente todas las preguntas.

En Windows, abre una terminal en la carpeta de Dynamic Xtreme y
ejecuta:

<pre>
.\dxt.exe -use-settings
</pre>

En Linux, ejecuta:

<pre>
./dxt -use-settings
</pre>

Si alguna ruta guardada ya no es válida, Dynamic Xtreme volverá al
modo interactivo para solicitar la configuración.

Las opciones disponibles son:

{| class="wikitable"
! Opción
! Alias
! Descripción
|-
| <code>-use-settings</code>
| <code>-us</code>
| Utiliza las rutas y funciones guardadas sin mostrar nuevamente las
preguntas.
|-
| <code>-verbose</code>
| <code>-v</code>
| Muestra información más detallada durante la instalación.
|-
| <code>-help</code>
|
| Muestra la ayuda y la lista de opciones disponibles.
|-
| <code>-version</code>
|
| Muestra la versión instalada de Dynamic Xtreme.
|}

Las opciones pueden combinarse. Por ejemplo, para utilizar la
configuración guardada y mostrar información detallada:

'''Windows:'''

<pre>
.\dxt.exe -use-settings -verbose
</pre>

'''Linux:'''

<pre>
./dxt -use-settings -verbose
</pre>

Para cambiar las rutas o las funciones seleccionadas, ejecuta Dynamic
Xtreme sin <code>-use-settings</code> y completa nuevamente las
preguntas.

== Finalizar la instalación ==

Tanto la instalación interactiva como la instalación mediante línea
de comandos producen el mismo resultado.

El resultado de la instalación queda guardado en <code>log.txt</code>, junto al ejecutable de Dynamic Xtreme. Este archivo contiene todos los detalles de la instalación.

Dynamic Xtreme prepara la integración con PIXI, UberASMTool y GPS,
pero no ejecuta estas herramientas. Después de instalar Dynamic
Xtreme, vuelve a ejecutar las herramientas externas que utilice tu
proyecto sobre la ROM de salida.

'''Cuándo reinstalar:'''

* Si cambias gráficos, paletas o archivos <code>*.dynamicinfo</code>, <code>*.drawinfo</code> o <code>*.paleffect</code>, reinstala Dynamic Xtreme y después las herramientas que utilicen esos recursos.
* Si añades, eliminas o modificas los includes de recursos <code>;#incdyn</code>, <code>;#incdri</code> o <code>;#incpale</code> dentro del ASM, también debes reinstalar Dynamic Xtreme y después las herramientas que utilicen esos recursos.
* Si solo modificas el código <code>*.asm</code>, sin cambiar esos includes, no necesitas reinstalar Dynamic Xtreme. Basta con volver a insertar el código con la herramienta correspondiente.

Cuando sea necesario reinstalar Dynamic Xtreme, el orden correcto es:

# Ejecutar Dynamic Xtreme para regenerar e instalar sus recursos.
# Volver a ejecutar PIXI, UberASMTool, GPS y cualquier otra
#: herramienta que utilice datos generados por Dynamic Xtreme.

Este orden es necesario porque las direcciones y los identificadores
de los recursos pueden cambiar cada vez que se ejecuta Dynamic
Xtreme.

es/Dynamic Xtreme sprite creation guide

2026-10-25T17:14:52Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_sprite_creation_guide}}

En este artículo se explicará cómo crear sprites dinámicos utilizando Dynamic Xtreme y PIXI.

La guía recorrerá el proceso completo: preparar los gráficos, definir las poses, incluir los archivos necesarios en el sprite y utilizar el sistema para cargar y dibujar sus poses en pantalla.

Si tienes dudas sobre los registros, parámetros o valores devueltos por una llamada, consulta la [[es/Dynamic_Xtreme_ASM_API|API ASM]]. Los apartados de esta guía incluyen enlaces a las llamadas correspondientes.

== Requisitos ==

Para seguir esta guía necesitas:

* Tener [https://www.smwcentral.net/?p=section&s=tools&f%5Bname%5D=PIXI PIXI] instalado y configurado para insertar sprites en tu ROM.
* Tener Dynamic Xtreme instalado y configurado. Si todavía no lo has hecho, consulta la [[Dynamic_Xtreme_Quick_Start|guía de inicio rápido]].

== Archivos utilizados por un sprite dinámico ==

Además de los archivos utilizados normalmente por PIXI, un sprite dinámico necesita los siguientes archivos:

* '''Archivo gráfico (*.bin):''' contiene los gráficos de las poses del sprite.
* '''DynamicInfo (*.dynamicinfo):''' indica qué gráficos utiliza el sprite y cómo se dividen en poses.
* '''DrawInfo (*.drawinfo):''' contiene la información necesaria para dibujar las poses.
* '''Archivo ASM (*.asm):''' contiene el código del sprite y utiliza los recursos anteriores.

Una posible estructura consiste en guardar los archivos de Dynamic Xtreme junto al propio recurso de PIXI. Por ejemplo, un sprite normal podría organizarse de la siguiente manera:

<pre>
PIXI/
└── sprites/
└── MySprite/
├── MySprite.asm
├── MySprite.json
└── DynamicXtreme/
├── MySprite.bin
├── MySprite.dynamicinfo
└── MySprite.drawinfo
</pre>

El archivo ASM y el archivo de configuración permanecen en la carpeta principal del sprite. Los gráficos, el DynamicInfo y el DrawInfo se guardan dentro de la subcarpeta <code>DynamicXtreme</code>.

En este caso, el ASM principal del sprite debe incluir el DynamicInfo y el DrawInfo mediante las siguientes directivas:

<pre>
;#incdyn "DynamicXtreme/MySprite.dynamicinfo"
;#incdri "DynamicXtreme/MySprite.drawinfo"
</pre>

Las rutas son relativas al archivo ASM que contiene las directivas. Si se trabaja con un cluster sprite, extended sprite u otro tipo admitido por PIXI, la carpeta completa del recurso puede organizarse de la misma manera dentro de la carpeta correspondiente de PIXI.

También es posible utilizar las carpetas tradicionales de Dynamic Xtreme. En ese caso, el archivo <code>*.dynamicinfo</code> se coloca en <code>DynamicInfos</code>, el archivo <code>*.drawinfo</code> en <code>DrawInfos</code> y los gráficos <code>*.bin</code> en <code>DynamicResources</code>. Los archivos guardados de esta forma son encontrados directamente por Dynamic Xtreme y no necesitan las directivas <code>;#incdyn</code> y <code>;#incdri</code> en el sprite.

La primera opción facilita distribuir el sprite con todos sus recursos dentro de una sola carpeta, mientras que la segunda mantiene la organización tradicional de Dynamic Xtreme. Para conocer la estructura y las reglas de cada formato, consulta [[Dynamic_Xtreme_files_and_formats|Archivos y formatos de Dynamic Xtreme]].

Durante la instalación, Dynamic Xtreme genera los defines que utilizará el código del sprite y los guarda en <code>DXDefines.asm</code>. Esta tabla resume el origen de los nombres utilizados en la guía:

{| class="wikitable"
! Define de ejemplo !! De dónde sale !! Para qué se utiliza
|-
| <code>!RenderBoxXDistanceOutOfScreenMySprite</code>
| Los límites horizontales de las poses de <code>MySprite.drawinfo</code>.
| Configurar la distancia horizontal del RenderBox en el INIT.
|-
| <code>!RenderBoxYDistanceOutOfScreenMySprite</code>
| Los límites verticales de las poses de <code>MySprite.drawinfo</code>.
| Configurar la distancia vertical del RenderBox en el INIT.
|-
| <code>!MySpritePaletteTableOffset</code>
| La lista <code>Palettes</code> de <code>MySprite.dynamicinfo</code>.
| Indicar a la asignación de paletas qué tabla utilizar.
|-
| <code>!DynamicPoseIDMySprite000</code>
| La primera pose de los gráficos <code>MySprite.bin</code>, declarados en <code>PosesGraphics</code> del DynamicInfo.
| Solicitar los gráficos de esa pose mediante <code>!Upload</code>. El sufijo <code>000</code> identifica la primera pose de ese archivo gráfico; <code>003</code>, la cuarta.
|-
| <code>!PoseIDMySprite_Frame0</code>
| La pose <code>Frame0</code> declarada en <code>MySprite.drawinfo</code>.
| Seleccionar la pose que dibujará <code>!DXDraw</code>.
|-
| <code>!PaletteEffectIDMyEffect0</code>
| El primer efecto de <code>MyEffect.paleffect</code>.
| Seleccionar el efecto de paleta que se aplicará.
|}

Los nombres se normalizan eliminando separadores y escribiendo en mayúscula la inicial de cada palabra: por ejemplo, <code>my_sprite</code> se convierte en <code>MySprite</code>. Consulta siempre los nombres exactos generados en <code>DXDefines.asm</code>; la guía también recuerda su origen junto a cada uso.

== Estructura del sprite ==

Un sprite dinámico conserva la estructura habitual de un sprite de PIXI, pero debe preparar las variables utilizadas por Dynamic Xtreme y organizar su rutina principal según se encuentre dentro o fuera de su área de renderizado.

La estructura que se utilizará en esta guía se divide en las siguientes partes:

* '''INIT:''' inicializa las variables del sprite y el estado utilizado por Dynamic Xtreme.
* '''Short routine:''' ejecuta la lógica que debe continuar incluso cuando el sprite se encuentra fuera del área de renderizado.
* '''Long routine:''' maneja las tareas que solamente son necesarias dentro del área de renderizado, como solicitar la pose y dibujarla.

=== Incluir los defines del tipo de sprite ===

Antes del código del sprite se debe incluir el archivo de defines correspondiente al tipo de recurso utilizado:

* <code>NormalSpriteDefines.asm</code> para sprites normales.
* <code>ClusterSpriteDefines.asm</code> para cluster sprites.
* <code>ExtendedSpriteDefines.asm</code> para extended sprites.

Por ejemplo, si el ASM de un sprite normal se encuentra dentro de una subcarpeta de <code>sprites</code>, el include puede escribirse de la siguiente manera:

<pre>
incsrc "../NormalSpriteDefines.asm"
</pre>

La ruta siempre es relativa a la ubicación del archivo ASM del sprite, por lo que debe ajustarse a la estructura de carpetas utilizada por el recurso. Este archivo proporciona los aliases de tablas y rutinas correspondientes a su tipo de sprite; gracias a esto, nombres como <code>!PoseIndex</code>, <code>!RenderBox</code> y <code>!Upload</code> apuntan a la implementación correcta para un sprite normal, cluster o extended.

=== INIT ===

En los sprites normales, la rutina <code>INIT</code> debe establecer las distancias utilizadas por el <code>RenderBox</code>, asignar los valores iniciales del sprite e invalidar cualquier estado anterior que pueda permanecer en el mismo slot de PIXI.

El siguiente ejemplo corresponde a un sprite normal. Inicia el sprite con la pose 0 y obtiene la versión y el volteo inicial desde la configuración de PIXI:

<pre>
print "INIT ",pc
LDA.b #!RenderBoxXDistanceOutOfScreenMySprite
STA !RenderXDistanceOutOfScreen,x
LDA.b #!RenderBoxYDistanceOutOfScreenMySprite
STA !RenderYDistanceOutOfScreen,x

LDA !ExtraBits,x
AND #$04
LSR
LSR
STA !GlobalFlip,x

LDA !ExtraByte1,x
AND #$0F
STA !Version,x

LDA #$00
STA !PoseIndex,x
STA !LocalFlip,x
STA !LastFlip,x

LDA #$FF
STA !Palette,x
STA !LastPoseIndex,x
STA !LastPoseHashIndex,x
STA !LastVersion,x

RTL
</pre>

Cada variable del ejemplo cumple una función concreta:

* <code>!RenderXDistanceOutOfScreen</code> y <code>!RenderYDistanceOutOfScreen</code> guardan las distancias que utilizará <code>!RenderBox</code> para decidir si el sprite todavía se encuentra lo bastante cerca de la pantalla como para renderizarse. Los valores <code>!RenderBoxXDistanceOutOfScreenMySprite</code> y <code>!RenderBoxYDistanceOutOfScreenMySprite</code> son generados a partir del DrawInfo y quedan disponibles en <code>DXDefines.asm</code>. El nombre del recurso se normaliza para formar el define: se eliminan separadores como espacios y guiones bajos, y la inicial de cada palabra se escribe en mayúscula. Por ejemplo, <code>my_sprite</code> y <code>my sprite</code> se convierten en <code>MySprite</code>.
* <code>!PoseIndex</code> indica la pose dinámica que el sprite desea utilizar dentro del DynamicInfo. El valor 0 selecciona la primera pose del recurso. Una rutina de animación puede asignar otro valor antes de solicitar los gráficos.
* <code>!Version</code> identifica la variante actual del sprite. Una versión puede cambiar su paleta, sus gráficos o incluso su comportamiento. En los sprites normales es habitual tomarla de los cuatro bits bajos de <code>!ExtraByte1,x</code>, lo que permite seleccionar hasta 16 versiones distintas desde Lunar Magic.
* <code>!GlobalFlip</code> representa el volteo general del sprite. En los sprites normales puede obtenerse del extra bit: 0 mantiene la orientación original y 1 aplica el volteo inicial. <code>!LocalFlip</code> permite aplicar un volteo adicional a la pose actual. Dynamic Xtreme combina ambos valores y conserva en <code>!LastFlip</code> el volteo efectivo utilizado para dibujar.
* <code>!Palette</code> guarda la paleta asignada actualmente. Se inicia en <code>$FF</code> porque el sprite todavía no posee una paleta válida.
* <code>!LastPoseIndex</code> guarda la última pose que Dynamic Xtreme pudo obtener correctamente, y <code>!LastPoseHashIndex</code> guarda el slot de la caché de VRAM donde se encuentra. Ambos comienzan en <code>$FF</code> porque todavía no existe una pose disponible.
* <code>!LastVersion</code> guarda la versión procesada anteriormente por el manejo de paletas. Iniciarla en <code>$FF</code> hace que la primera versión del sprite sea procesada aunque <code>!Version</code> comience en 0.

Si un sprite utiliza varios DrawInfo, las distancias deben cubrir el conjunto completo de sus gráficos. Se recomienda revisar en <code>DXDefines.asm</code> los valores generados para cada DrawInfo y utilizar la mayor distancia horizontal y la mayor distancia vertical. Por ejemplo, si la cabeza y el cuerpo utilizan DrawInfo diferentes, tomar solamente las distancias de la cabeza podría hacer que el sprite deje de dibujarse cuando una parte de su cuerpo todavía se encuentra dentro de la pantalla.

Los valores marcados con <code>$FF</code> representan estados inválidos. Además de indicar que el sprite todavía no tiene una paleta o pose disponible, evitan reutilizar información dejada por otro sprite que haya ocupado anteriormente el mismo slot de PIXI.

==== Inicialización de cluster y extended sprites ====

Los cluster sprites y extended sprites no tienen una rutina <code>INIT</code> propia. Para inicializarlos una sola vez se reserva una de sus tablas, por ejemplo <code>!ClusterMiscTable1</code> o <code>!ExtendedMiscTable1</code>, y se le asigna un nombre como <code>!Started</code>:

<pre>
!Started = !ClusterMiscTable1
</pre>

Cuando se crea el sprite, <code>!Started</code> debe establecerse en 0 utilizando el índice del nuevo cluster o extended sprite. Esto es necesario porque el slot pudo haber sido utilizado anteriormente y todavía podría contener el valor de otro sprite.

Al comienzo de <code>SpriteCode</code>, antes de ejecutar <code>!RenderBox</code>, se comprueba esta variable:

<pre>
SpriteCode:
LDA !Started,x
BNE +
JSR Start
RTS
+
!RenderBox
; Resto del código del sprite
</pre>

La rutina <code>Start</code> contiene la inicialización que un sprite normal realizaría en <code>INIT</code>. Al finalizar, establece <code>!Started</code> en 1 para que no vuelva a ejecutarse durante los frames siguientes:

<pre>
Start:
; Aquí va la inicialización del sprite

LDA #$01
STA !Started,x
RTS
</pre>

Como <code>Start</code> se llama mediante <code>JSR</code>, debe terminar con <code>RTS</code>. El código que crea el cluster o extended sprite también debe preparar cualquier dato que deba heredarse del sprite principal, como <code>!PaletteOption</code>, <code>!PaletteAssignmentOption</code> o <code>!GlobalFlip</code>.

==== PaletteOption ====

<code>!PaletteOption</code> controla la paleta solicitada y si esta será afectada por el efecto global de paleta. Su formato es el siguiente:

<pre>
EPPP----
</pre>

* <code>E</code> indica si la paleta será afectada por el efecto global: 0 la excluye y 1 lo habilita.
* <code>PPP</code> representa una paleta entre 8 y F: <code>000</code> corresponde a la paleta 8 y <code>111</code> a la paleta F.
* Los cuatro bits bajos no forman parte de <code>PaletteOption</code>.

Cuando se utiliza asignación automática, <code>PPP = 000</code> permite buscar un slot libre entre las ocho paletas, un valor <code>0XX</code> distinto de <code>000</code> limita la búsqueda a las paletas 8-B y un valor <code>1XX</code> la limita a las paletas C-F. Con asignación manual, <code>PPP</code> selecciona directamente la paleta que se utilizará.

En los sprites normales, <code>!PaletteOption</code> utiliza directamente <code>!ExtraByte1,x</code>. Lo habitual es aprovechar los cuatro bits restantes para seleccionar la versión del sprite, por lo que el byte completo utiliza el siguiente formato:

<pre>
EPPPVVVV
</pre>

* <code>EPPP</code> contiene las opciones de paleta descritas anteriormente.
* <code>VVVV</code> selecciona una de las 16 versiones posibles del sprite, desde 0 hasta 15.

<code>!PaletteOption</code> utiliza los cuatro bits altos directamente, mientras que el <code>INIT</code> copia los cuatro bits bajos a <code>!Version</code>. No es necesario copiar <code>PaletteOption</code> a otra tabla.

==== PaletteAssignmentOption ====

<code>!PaletteAssignmentOption</code> determina cómo se asignará la paleta al sprite:

<pre>
--AA----
</pre>

* <code>AA = 00</code>: '''asignación automática'''. Dynamic Xtreme busca un slot permitido por <code>PaletteOption</code> y carga la paleta dinámicamente.
* <code>AA = 01</code>: '''asignación manual'''. <code>PaletteOption</code> indica el slot exacto y Dynamic Xtreme carga la paleta dinámicamente.
* <code>AA = 10</code>: '''asignación manual sin carga'''. El sprite utiliza directamente la paleta que ya existe en el nivel y Dynamic Xtreme no carga una nueva.

En los sprites normales, <code>!PaletteAssignmentOption</code> utiliza directamente <code>!ExtraProp2,x</code>. Por lo tanto, el modo se configura mediante los bits 5 y 4 del Extra Property Byte 2 y tampoco necesita copiarse a otra tabla durante el <code>INIT</code>.

En los cluster sprites y extended sprites, <code>!PaletteOption</code> y <code>!PaletteAssignmentOption</code> deben establecerse manualmente cuando son creados. Normalmente se copia el modo de asignación del sprite que los genera. Al copiar <code>PaletteOption</code>, sus cuatro bits bajos deben borrarse porque en un sprite normal contienen la versión y no forman parte de la opción de paleta.

Si el sprite generado utiliza la misma paleta que el sprite principal, puede copiar su <code>PaletteOption</code> después de borrar los cuatro bits bajos. Si utiliza una paleta distinta y el sprite principal emplea asignación automática, puede conservarse el mismo rango de búsqueda. Si el sprite principal emplea asignación manual o asignación manual sin carga, se suma <code>$10</code> al valor enmascarado para seleccionar la paleta siguiente.

En este último caso, el sprite principal no puede utilizar la paleta F, porque el sprite generado necesita la paleta siguiente. Debes configurar el sprite principal con una paleta entre la 8 y la E.

Además de estas variables, el <code>INIT</code> puede inicializar cualquier tabla propia que necesite el comportamiento del sprite.

=== SpriteCode ===

Consulta en la API las entradas y el resultado de [[es/Dynamic_Xtreme_ASM_API#RenderBox|RenderBox]].

<code>SpriteCode</code> comienza ejecutando <code>!RenderBox</code>. Esta rutina devuelve el carry activado cuando el sprite se encuentra dentro de su área de renderizado y desactivado cuando está fuera de ella. Con este resultado se decide si ejecutar la short routine o la long routine.

Una estructura base puede escribirse de la siguiente manera:

<pre>
SpriteCode:
!RenderBox
BCS .LongRoutine

.ShortRoutine
LDA #$00
%SubOffScreen()
; Aquí va la lógica de tu sprite
RTS

.LongRoutine
JSR PaletteManagement
BCC ..Return

JSR PoseManagement
BCC ..Return

JSR Draw
; Aquí va la lógica de tu sprite
..Return
RTS
</pre>

==== Short routine ====

La short routine se ejecuta cuando el sprite se encuentra fuera del área calculada por <code>!RenderBox</code>. Aquí solamente debe ejecutarse la lógica base necesaria para mantener el comportamiento del sprite, sin solicitar gráficos dinámicos, procesar su paleta ni dibujarlo. El contenido exacto depende del sprite y puede incluir su movimiento, estado, temporizadores, interacciones o animación.

En los sprites normales se recomienda llamar a <code>%SubOffScreen()</code> dentro de esta parte. Recibe en A un valor entre 0 y 7 para seleccionar la configuración de eliminación fuera de pantalla; el ejemplo utiliza 0, el valor habitual. De esta manera PIXI puede eliminar el sprite cuando se aleja lo suficiente de la pantalla, sin ejecutar esta comprobación durante la parte más costosa del renderizado.

==== Long routine ====

La long routine se ejecuta cuando el sprite está dentro del área de renderizado. Esta ruta realiza el proceso completo: maneja la paleta, solicita la pose dinámica o actualiza su registro de uso si ya está en VRAM para evitar que sea sobrescrita, dibuja el sprite y finalmente ejecuta la misma lógica base de la short routine.

No es necesario llamar nuevamente a <code>%SubOffScreen()</code> dentro de la long routine. Como <code>!RenderBox</code> ya determinó que el sprite se encuentra dentro del área de renderizado, realizar allí la comprobación resulta redundante.

<code>PaletteManagement</code> y <code>PoseManagement</code> devuelven el carry activado cuando existe un recurso utilizable. Si alguna de ellas devuelve el carry desactivado, el ejemplo salta a <code>..Return</code> y termina la rutina. En ese caso, no se dibuja el sprite ni se ejecuta la lógica que viene después durante ese frame.

Las rutinas de paleta, poses y dibujo se desarrollarán en los apartados siguientes. Los nombres utilizados aquí son solamente una forma de organizar el código y pueden cambiarse según la estructura del sprite.

== Manejo de Paleta de Colores ==

=== Cargar una paleta dinámica ===

Consulta en la API los detalles de [[es/Dynamic_Xtreme_ASM_API#PaletteAssignment|PaletteAssignment]].

Para utilizar la asignación de paletas en un sprite normal, su archivo <code>*.cfg</code> o <code>*.json</code> debe tener configurado al menos un Extra Byte:

* '''Extra Byte 1:''' proporciona <code>!PaletteOption</code> y, en el ejemplo de esta guía, sus cuatro bits bajos seleccionan <code>!Version</code>.
* '''Extra Property Byte 2:''' configura <code>!PaletteAssignmentOption</code> mediante sus bits 5 y 4: <code>00</code> para asignación automática, <code>01</code> para asignación manual y <code>10</code> para asignación manual sin carga. Estos bits corresponden a los valores <code>$00</code>, <code>$10</code> y <code>$20</code>, respectivamente; los demás bits pueden utilizarse para otras opciones del sprite.

La carga de una paleta dinámica se realiza mediante <code>!PaletteAssignment</code>. Solamente se debe cargar en A, con 16 bits, el offset de la tabla de paletas generado para el recurso:

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignment
RTS
</pre>

El define <code>!MySpritePaletteTableOffset</code> se genera a partir de las paletas declaradas en el DynamicInfo y queda disponible en <code>DXDefines.asm</code>. El nombre del DynamicInfo se normaliza eliminando espacios, guiones bajos y otros separadores, y escribiendo en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_sprite.dynamicinfo</code> genera el componente <code>MySprite</code>.

<code>!PaletteAssignment</code> utiliza <code>!Version</code> para seleccionar una entrada de la tabla: la versión 0 utiliza la primera paleta, la versión 1 utiliza la segunda y así sucesivamente. También utiliza <code>!PaletteOption</code> y <code>!PaletteAssignmentOption</code> para decidir dónde y cómo asignarla.

La rutina devuelve el carry activado cuando existe una paleta utilizable y desactivado cuando todavía no fue posible obtenerla. Por esta razón, <code>SpriteCode</code> comprueba el carry antes de continuar con la carga de poses y el dibujo. <code>!PaletteAssignment</code> debe ejecutarse en cada frame de la long routine para conservar la asignación mientras el sprite siga utilizándola.

=== Seleccionar una paleta sin cambiar la versión del sprite ===

La paleta de un sprite puede cambiar sin que su versión o su comportamiento tengan que cambiar. Por ejemplo, un sprite puede alternar entre su paleta normal y una segunda paleta durante una animación o un estado temporal. Mantener ambas paletas como recursos independientes también permite que la segunda sea reutilizada por otros sprites.

Como <code>!PaletteAssignment</code> selecciona la entrada mediante <code>!Version</code>, puede guardarse temporalmente la versión lógica del sprite, asignar el índice de la paleta deseada y restaurar después el valor original:

<pre>
PaletteManagement:
LDA !Version,x
PHA

LDA #$02
STA !Version,x

REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignment

PLA
STA !Version,x
RTS
</pre>

En este ejemplo, <code>!PaletteAssignment</code> utiliza la entrada 2 de la tabla, pero el comportamiento del sprite conserva su versión original. De esta forma, la selección de la paleta queda separada de la variante lógica del personaje. <code>PLA</code> y <code>STA</code> no alteran el carry, por lo que <code>PaletteManagement</code> todavía devuelve correctamente el resultado de <code>!PaletteAssignment</code>.

El define <code>!MySpritePaletteTableOffset</code> utilizado aquí se genera desde el DynamicInfo y se encuentra en <code>DXDefines.asm</code>. Su nombre usa la misma normalización: se eliminan separadores y se escribe en mayúscula la inicial de cada palabra, de modo que <code>my_sprite</code> se convierte en <code>MySprite</code>.

=== Concatenar un efecto local con el efecto global ===

Consulta en la API los detalles de [[es/Dynamic_Xtreme_ASM_API#PaletteAssignmentNoUpload|PaletteAssignmentNoUpload]], [[es/Dynamic_Xtreme_ASM_API#ConcatenateRGBPaletteEffectToGlobal|ConcatenateRGBPaletteEffectToGlobal]] y [[es/Dynamic_Xtreme_ASM_API#ConcatenateHSLPaletteEffectToGlobal|ConcatenateHSLPaletteEffectToGlobal]].

Cuando la paleta necesita un efecto propio que además debe combinarse con el efecto global de paleta, se utiliza <code>!PaletteAssignmentNoUpload</code> seguido de <code>!ConcatenateRGBPaletteEffectToGlobal</code> o <code>!ConcatenateHSLPaletteEffectToGlobal</code>:

<pre>
PaletteManagement:
REP #$20
LDA #!MySpritePaletteTableOffset
!PaletteAssignmentNoUpload
BCC .Return

PHY

LDA !Palette,x
TAX

LDA $14
AND #$06
TAY

REP #$20
LDA PaletteEffects,y

PLY
!ConcatenateRGBPaletteEffectToGlobal

.Return
RTS

PaletteEffects:
dw !PaletteEffectIDMyEffect0
dw !PaletteEffectIDMyEffect1
dw !PaletteEffectIDMyEffect2
dw !PaletteEffectIDMyEffect3
</pre>

<code>!PaletteAssignmentNoUpload</code> asigna la paleta y prepara su dirección base sin realizar todavía la carga final. También deja en Y la información que la rutina de concatenación necesita para decidir si debe reconstruir el efecto.

En este ejemplo se utiliza <code>$14</code>, el contador principal de frames de Super Mario World, para seleccionar uno de cuatro efectos. Como Y se necesita temporalmente para leer la tabla <code>PaletteEffects</code>, primero se conserva con <code>PHY</code> y se restaura con <code>PLY</code>. El valor restaurado debe llegar sin modificaciones a la rutina de concatenación.

Antes de concatenar, X debe contener el valor de <code>!Palette</code>, que ya representa el índice requerido por la rutina. A debe contener, con 16 bits, el ID del efecto local. En el ejemplo, Y se utiliza como índice para cargar ese ID desde una tabla, pero el ID finalmente se entrega en A.

El define <code>!MySpritePaletteTableOffset</code> se genera desde el DynamicInfo y se encuentra en <code>DXDefines.asm</code>. Los defines <code>!PaletteEffectIDMyEffectX</code> son generados a partir de un archivo <code>*.paleffect</code> durante la instalación y se guardan en el mismo archivo. En ambos casos los nombres se normalizan eliminando espacios, guiones bajos y otros separadores, y escribiendo en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_effect.paleffect</code> genera el componente <code>MyEffect</code>; <code>X</code> corresponde al índice del efecto dentro de la colección.

Se utiliza <code>!ConcatenateRGBPaletteEffectToGlobal</code> para efectos que trabajan en RGB, como <code>PaletteTransitionRGB</code>, y <code>!ConcatenateHSLPaletteEffectToGlobal</code> para efectos que trabajan en HSL, como <code>MixH</code>. Para combinar el efecto local con el global, el bit <code>E</code> de <code>PaletteOption</code> debe estar activado. La rutina realiza internamente las conversiones necesarias cuando ambos efectos utilizan espacios de color diferentes. Para conocer el espacio de color de cada efecto, consulta [https://sneslab.net/wiki/es/Dynamic_Xtreme_files_and_formats#Tipos_de_efectos Tipos de efectos].

La concatenación devuelve el carry activado cuando existe un resultado utilizable, incluido un resultado anterior usado como respaldo, y desactivado cuando esa paleta todavía no posee ningún resultado válido. Este carry debe conservarse para que <code>SpriteCode</code> pueda decidir si continúa con el dibujo.

== Manejo de Poses Dinámicas ==

Las poses dinámicas se solicitan mediante <code>!Upload</code> o <code>!UploadWithoutPoseOffset</code>. Estas rutinas buscan la pose en la caché de VRAM y, si todavía no está disponible, solicitan su carga. Deben ejecutarse en cada frame de la long routine para mantener activa la pose que utiliza el sprite.

=== Upload ===

Consulta en la API los detalles de [[es/Dynamic_Xtreme_ASM_API#Upload|Upload]].

<code>!Upload</code> recibe en A, con 16 bits, el ID dinámico base del recurso y le suma el valor de <code>!PoseIndex</code>:

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite000
!Upload
RTS
</pre>

En este ejemplo, si <code>!PoseIndex</code> contiene 0 se solicita la primera pose; si contiene 1 se solicita la pose siguiente, y así sucesivamente. Esto permite que la rutina de animación cambie solamente <code>!PoseIndex</code> mientras <code>PoseManagement</code> conserva el mismo ID base.

El define <code>!DynamicPoseIDMySprite000</code> se genera a partir del DynamicInfo durante la instalación de Dynamic Xtreme y queda disponible en <code>DXDefines.asm</code>. El nombre se normaliza eliminando espacios, guiones bajos y otros separadores, y escribiendo en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_sprite.dynamicinfo</code> genera el componente <code>MySprite</code>.

<code>!Upload</code> devuelve el carry activado cuando existe una pose utilizable. Esta puede ser la pose solicitada durante el frame actual o la última pose válida del sprite, utilizada como respaldo mientras la nueva termina de cargarse. El carry se devuelve desactivado solamente cuando el sprite todavía no posee ninguna pose que pueda utilizar.

Cuando la solicitud tiene éxito, <code>!LastPoseIndex</code> guarda la pose realmente disponible y <code>!LastPoseHashIndex</code> guarda su posición dentro de la caché de VRAM. Por esta razón, el dibujo debe utilizar el estado de la última pose disponible y no asumir que <code>!PoseIndex</code> ya fue cargado.

=== UploadWithoutPoseOffset ===

Consulta en la API los detalles de [[es/Dynamic_Xtreme_ASM_API#UploadWithoutPoseOffset|UploadWithoutPoseOffset]].

<code>!UploadWithoutPoseOffset</code> también recibe un ID dinámico en A con 16 bits, pero lo utiliza directamente y no le suma <code>!PoseIndex</code>:

<pre>
PoseManagement:
REP #$20
LDA #!DynamicPoseIDMySprite003
!UploadWithoutPoseOffset
RTS
</pre>

Esta variante es útil cuando el código ya seleccionó el ID dinámico exacto, por ejemplo mediante una tabla o una condición propia. Su carry tiene el mismo significado que en <code>!Upload</code>: activado cuando existe una pose utilizable y desactivado cuando todavía no existe ninguna.

El define <code>!DynamicPoseIDMySprite003</code> también es generado desde el DynamicInfo y se encuentra en <code>DXDefines.asm</code>. Su nombre utiliza la misma normalización de estilo CamelCase: se eliminan los separadores y se escribe en mayúscula la inicial de cada palabra.

Actualmente <code>!UploadWithoutPoseOffset</code> está publicado por los archivos de defines para sprites normales y cluster sprites. Los extended sprites deben utilizar <code>!Upload</code> junto con <code>!PoseIndex</code> mientras su archivo de defines no publique este alias.

Los defines <code>!DynamicPoseID...</code> pertenecen al sistema de carga dinámica. No deben confundirse con los defines <code>!PoseID...</code> del DrawInfo, que se utilizan posteriormente para dibujar la pose.

== Dibujar Poses en Pantalla ==

Una vez que <code>PoseManagement</code> ha obtenido una pose utilizable, esta puede dibujarse mediante <code>!DXDraw</code> o <code>!DXDrawWithOffset</code>. Ambas rutinas utilizan la posición, el volteo, la paleta y la pose dinámica que Dynamic Xtreme conserva para el sprite.

Antes de llamar a cualquiera de las dos rutinas deben prepararse los siguientes valores:

* A, con 16 bits, contiene el ID de la pose de dibujo.
* <code>!PropParam</code> contiene propiedades adicionales con el formato <code>YXCC----</code>.
* <code>!MaxTilePriorityParam</code> indica la prioridad máxima que pueden utilizar los tiles de la pose.

Los valores admitidos por <code>!MaxTilePriorityParam</code> son:

* <code>$00</code>: prioridad máxima.
* <code>$01</code>: prioridad alta.
* <code>$02</code>: prioridad propia del tipo de sprite.
* <code>$03</code>: prioridad mínima.

=== DXDraw ===

Consulta en la API los detalles de [[es/Dynamic_Xtreme_ASM_API#DXDraw|DXDraw]].

<code>!DXDraw</code> dibuja la pose tomando como origen la posición normal del sprite. Una rutina de dibujo básica puede escribirse de la siguiente manera:

<pre>
Draw:
LDA #$20
STA !PropParam

LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDraw
RTS
</pre>

El valor de <code>!LastPoseIndex</code> se suma al primer ID de dibujo para seleccionar la pose que realmente se encuentra disponible. Es importante utilizar <code>!LastPoseIndex</code> y no <code>!PoseIndex</code>: mientras una pose nueva termina de cargarse, Dynamic Xtreme puede conservar la pose anterior como respaldo.

Este ejemplo supone que las poses del DrawInfo siguen el mismo orden que las poses del DynamicInfo. Si el orden es diferente, el código debe convertir <code>!LastPoseIndex</code> al ID de dibujo correspondiente, por ejemplo mediante una tabla.

El define <code>!PoseIDMySprite_Frame0</code> es generado a partir del DrawInfo durante la instalación y queda disponible en <code>DXDefines.asm</code>. Los nombres generados se normalizan eliminando espacios, guiones bajos y otros separadores, y escribiendo en mayúscula la inicial de cada palabra. Por ejemplo, <code>my_sprite</code> genera el componente <code>MySprite</code>.

Los defines <code>!PoseID...</code> identifican poses de dibujo declaradas en un DrawInfo. No deben confundirse con los defines <code>!DynamicPoseID...</code> del DynamicInfo, que se utilizan con <code>!Upload</code> para solicitar los gráficos dinámicos.

<code>!DXDraw</code> combina las propiedades indicadas en <code>!PropParam</code> con <code>!LastFlip</code>, la paleta asignada y las propiedades propias de la pose. También utiliza <code>!LastPoseHashIndex</code> para localizar sus gráficos en la caché de VRAM. Si este valor contiene <code>$FF</code>, la rutina no dibuja nada.

=== DXDrawWithOffset ===

Consulta en la API los detalles de [[es/Dynamic_Xtreme_ASM_API#DXDrawWithOffset|DXDrawWithOffset]].

<code>!DXDrawWithOffset</code> funciona de la misma forma, pero permite desplazar el dibujo con respecto a la posición del sprite. Los desplazamientos se entregan como valores de 8 bits con signo mediante <code>!XOffsetParam</code> y <code>!YOffsetParam</code>:

<pre>
Draw:
LDA #$08
STA !XOffsetParam

LDA #$F8
STA !YOffsetParam

LDA #$20
STA !PropParam

LDA #$02
STA !MaxTilePriorityParam

LDA !LastPoseIndex,x
REP #$21
AND #$00FF
ADC #!PoseIDMySprite_Frame0
!DXDrawWithOffset
RTS
</pre>

En este ejemplo, el dibujo se desplaza 8 píxeles hacia la derecha y 8 píxeles hacia arriba. Un valor positivo en X desplaza la pose hacia la derecha y uno negativo hacia la izquierda; en Y, un valor positivo la desplaza hacia abajo y uno negativo hacia arriba.

El offset solamente modifica la posición donde se dibuja la pose. No cambia la posición real del sprite, su hitbox ni sus interacciones. Esto resulta útil para alinear gráficos, aplicar movimientos visuales o dibujar varias partes de una entidad desde una misma posición lógica.

Al igual que en el ejemplo anterior, <code>!PoseIDMySprite_Frame0</code> es un define generado desde el DrawInfo y guardado en <code>DXDefines.asm</code>. Su nombre utiliza la normalización de Dynamic Xtreme: elimina separadores como espacios y guiones bajos, y escribe en mayúscula la inicial de cada palabra.

=== DrawStatic ===

Consulta en la API los detalles de [[es/Dynamic_Xtreme_ASM_API#DrawStatic|DrawStatic]].

El sistema de dibujo de Dynamic Xtreme también puede utilizarse con poses estáticas. Estas poses se declaran mediante <code>.IsStatic</code> en el DrawInfo y se dibujan con la macro <code>%DrawStatic()</code>. Como sus gráficos ya se encuentran disponibles en la VRAM, no necesitan <code>!Upload</code>, <code>!LastPoseIndex</code> ni <code>!LastPoseHashIndex</code>.

Cuando una pose estática utiliza el tile predeterminado (0) para todos sus componentes, el dibujo toma el número de tile desde <code>!Tile</code>, que representa la scratch RAM <code>$05</code>. Esto permite reutilizar una misma pose, por ejemplo una de un solo tile, para dibujar distintos gráficos. El sprite debe preparar el valor antes de llamar a <code>%DrawStatic()</code>:

<pre>
LDA #$80 ; Número de tile que se desea dibujar
STA !Tile ; Scratch RAM $05
</pre>

Este valor debe prepararse en cada llamada de dibujo que lo necesite; no basta con establecerlo durante el INIT, porque la scratch RAM se comparte con otras rutinas.

En las poses dinámicas, <code>!DXDraw</code> y <code>!DXDrawWithOffset</code> obtienen el tile desde la ubicación de los gráficos en la caché de VRAM. En ese caso no es necesario preparar <code>!Tile</code> manualmente. Si una pose estática declara tiles distintos del predeterminado en su DrawInfo, el dibujo utiliza esos valores directamente.

El siguiente ejemplo dibuja una pose estática en la posición de un sprite normal, sin volteo y utilizando la paleta A:

<pre>
Draw:
LDA #$20
STA !PropParam

LDA #$02
STA !MaxTilePriorityParam

REP #$21
LDA #!PoseIDMyStaticSprite_Frame0
%DrawStatic(0, 1, #$00, #$04, "!SpriteXLow,x", "!SpriteXHigh,x", "!SpriteYLow,x", "!SpriteYHigh,x")
</pre>

El primer parámetro indica si se utilizarán offsets adicionales: 0 dibuja en la posición entregada y 1 aplica también <code>!XOffsetParam</code> y <code>!YOffsetParam</code>. Los parámetros siguientes proporcionan el contexto del dibujo, el volteo, la paleta y las posiciones X e Y de 16 bits. Las posiciones indexadas se escriben entre comillas para que la coma de <code>,x</code> no sea interpretada como un separador de parámetros de la macro.

<code>%DrawStatic()</code> finaliza la rutina mediante <code>RTS</code>, por lo que no se coloca otro <code>RTS</code> después de la llamada en este ejemplo.

En el ejemplo, <code>#$00</code> indica que la pose no se voltea y <code>#$04</code> selecciona la paleta A. Estos argumentos también pueden utilizar tablas o variables cuando el sprite necesite cambiar su orientación o paleta.

El define <code>!PoseIDMyStaticSprite_Frame0</code> se genera desde el DrawInfo durante la instalación y queda disponible en <code>DXDefines.asm</code>. Su nombre se normaliza en PascalCase: se eliminan espacios, guiones bajos, guiones y otros separadores, y se escribe en mayúscula la inicial de cada palabra.

Para obtener más información sobre la declaración de poses estáticas, consulta [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos de Dynamic Xtreme]].

== Instalar y probar el sprite ==

Cada vez que se modifique alguno de los recursos procesados por Dynamic Xtreme, se debe reinstalar primero Dynamic Xtreme y después volver a insertar los sprites con PIXI. Esto incluye cambios en archivos <code>*.dynamicinfo</code>, <code>*.drawinfo</code>, gráficos <code>*.bin</code>, efectos <code>*.paleffect</code> y cualquier otro recurso dinámico utilizado por el sprite.

El orden es importante: Dynamic Xtreme debe procesar primero los recursos y regenerar sus datos y defines; después PIXI puede ensamblar el sprite utilizando la información actualizada.

Si añades, eliminas o modificas los includes de recursos <code>;#incdyn</code>, <code>;#incdri</code> o <code>;#incpale</code> dentro del ASM, también debes reinstalar primero Dynamic Xtreme y después PIXI.

Si solo modificas el código <code>*.asm</code> del sprite, sin cambiar esos includes, no es necesario reinstalar Dynamic Xtreme. En ese caso basta con ejecutar PIXI nuevamente.

Para conocer el proceso completo de instalación, configuración y reinstalación de recursos, consulta la [[Dynamic_Xtreme_Quick_Start|guía de inicio rápido de Dynamic Xtreme]].

Después de cada instalación, prueba el sprite en el juego y comprueba que sus poses, paletas, volteos y desplazamientos se muestren correctamente durante sus diferentes estados y animaciones.

== Errores comunes ==

=== Utilizar un nombre sin normalizar en un define generado ===

Los nombres incluidos en los defines generados por Dynamic Xtreme deben escribirse con la normalización utilizada por la herramienta. Los espacios, guiones bajos y guiones se eliminan, y la primera letra de cada palabra se escribe en mayúscula siguiendo el estilo PascalCase.

Por ejemplo, una pose llamada <code>my_sprite-pose</code> utiliza el componente normalizado <code>MySpritePose</code> dentro de un define como el siguiente:

<pre>
!DynamicPoseIDMySpritePose
</pre>

Escribir el nombre original con sus separadores, utilizar una combinación distinta de mayúsculas o confundir un define <code>!DynamicPoseID...</code> con un <code>!PoseID...</code> hará que Asar no encuentre el símbolo. Ante una duda, revisa el nombre exacto generado en <code>DXDefines.asm</code>.

=== Inicializar incorrectamente las variables del sprite ===

Las variables utilizadas por Dynamic Xtreme deben recibir valores válidos cada vez que se crea un sprite. Cuando se utiliza <code>!PaletteAssignment</code>, <code>!Palette</code>, <code>!LastPoseIndex</code>, <code>!LastPoseHashIndex</code> y <code>!LastVersion</code> deben comenzar en <code>$FF</code>, mientras que variables como <code>!PoseIndex</code>, <code>!LocalFlip</code> y <code>!LastFlip</code> normalmente comienzan en 0. También deben configurarse las distancias utilizadas por <code>!RenderBox</code>.

Si estas tablas no se inicializan correctamente, el sprite puede reutilizar una paleta, una pose o información dejada por otro sprite que ocupó anteriormente el mismo slot. En cluster sprites y extended sprites, esta inicialización debe realizarse mediante la rutina de inicio simulada explicada anteriormente.

=== No reservar un Extra Byte para la paleta ===

Un sprite normal que utilice carga de paletas debe tener disponible al menos un Extra Byte en su archivo <code>*.cfg</code> o <code>*.json</code>. Dynamic Xtreme utiliza <code>Extra Byte 1</code> como <code>!PaletteOption</code> y, normalmente, también aprovecha sus cuatro bits bajos para seleccionar <code>!Version</code>.

Si el sprite no declara ningún Extra Byte, <code>!ExtraByte1,x</code> no contendrá la configuración necesaria para seleccionar correctamente la paleta y la versión del sprite.

=== No restaurar una paleta fija en la short routine ===

Un sprite puede utilizar una paleta fija que ya se encuentre cargada en el nivel en lugar de llamar a <code>!PaletteAssignment</code>. En este caso todavía es necesario asignar manualmente a <code>!Palette,x</code> el valor de la paleta que utilizará el dibujo.

Los valores avanzan de dos en dos y corresponden a las paletas de sprites 8-F:

* <code>$00</code>: paleta 8.
* <code>$02</code>: paleta 9.
* <code>$04</code>: paleta A.
* <code>$06</code>: paleta B.
* <code>$08</code>: paleta C.
* <code>$0A</code>: paleta D.
* <code>$0C</code>: paleta E.
* <code>$0E</code>: paleta F.

El valor debe asignarse durante el <code>INIT</code> y también dentro de la short routine. Cuando <code>!RenderBox</code> envía el sprite a la short routine, invalida <code>!Palette,x</code>; por eso la paleta fija debe restaurarse en esa ruta:

<pre>
; Dentro de INIT
LDA #$04 ; Paleta A
STA !Palette,x

; Dentro de SpriteCode
.ShortRoutine
LDA #$04 ; Paleta A
STA !Palette,x

LDA #$00
%SubOffScreen()
; Aquí va la lógica de tu sprite
RTS
</pre>

Esta asignación manual solamente corresponde a sprites que utilizan una paleta fija y no llaman a <code>!PaletteAssignment</code>. Los sprites con carga dinámica deben conservar el flujo de asignación explicado en la sección de manejo de paletas.

es/Dynamic Xtreme sprite creation guide

2026-10-25T17:14:03Z

Anonimzwx:

# Revisión de Dynamic_Xtreme_dynamic_sprite_creation_guide.wiki

Fecha: 24 de octubre de 2026. Fuente: `docs/SNESLab/es/Dynamic_Xtreme_dynamic_sprite_creation_guide.wiki`.

Perspectiva de una primera lectura, sin conocimiento previo del proyecto. Se evalúan explicaciones y coherencia de los fragmentos publicados; no se analizaron archivos ASM ni se ensamblaron ejemplos. Alta: puede bloquear el tutorial o inducir una aplicación incorrecta; media: exige deducciones; baja: presentación.

## Qué entendí

El sprite prepara su estado, comprueba si debe renderizarse, obtiene paleta y pose y después dibuja la última pose disponible. Entendí por qué no se debe dibujar directamente la pose solicitada si todavía no está disponible. La descripción de las variables iniciales y de los estados inválidos ayuda a seguir ese proceso.

## Observaciones y recomendaciones

### 1. El ejemplo contradice la explicación sobre el fallo de recursos — Alta

**Dónde:** SpriteCode, líneas 223–237, y explicación de la long routine, línea 252.

**Evidencia:** los dos fallos usan `BCC ..Return`; el texto dice que «el ejemplo salta a .ShortRoutine» y que la lógica continúa. En el fragmento, la lógica está antes del retorno y se omite al tomar esos saltos.

**Duda:** «¿El sprite debe detener su movimiento cuando falta una paleta o pose? ¿Qué flujo debo copiar?». La discrepancia es visible en el propio artículo, sin necesitar conocer las rutinas internas.

**Recomendación:** hacer que explicación y ejemplo describan un único recorrido, indicando dónde se ejecuta la lógica en éxito y en fallo. Una pequeña tabla de los tres casos —fuera del área, recursos disponibles y recursos no disponibles— permitiría revisarlo. Validar después el ejemplo real antes de publicarlo.

**Resolución:** aplicada al texto, conservando el ejemplo. El autor confirmó que, si falla la solicitud de paleta o pose, se debe retornar, sin pasar por la short routine. Se corrigió la explicación para indicar que los saltos a `..Return` terminan la rutina y omiten tanto el dibujo como la lógica posterior durante ese frame.

### 2. El proceso completo prometido no incluye un recurso completo — Alta

**Dónde:** introducción, archivos y resto de la guía.

**Duda:** «¿Dónde preparo los gráficos? ¿Qué escribo exactamente en MySprite.dynamicinfo y MySprite.drawinfo? ¿Cómo conecto SpriteCode con MAIN?». Hay un árbol de archivos y rutinas aisladas, pero no una secuencia completa de creación de esos archivos ni un sprite mínimo terminado.

**Recomendación:** comenzar con una pose de un tile y una paleta, mostrar todos los archivos necesarios y la configuración de PIXI, y terminar con su inserción y resultado. Enlazar formatos para ampliar el ejemplo, sin delegar allí los pasos mínimos del tutorial. Separar luego cluster, extended, efectos locales y dibujo estático como variantes.

**Resolución:** descartada. El autor indica que habrá numerosos recursos completos disponibles en snestorage.dev, por lo que no se añadirá un sprite mínimo completo con todos sus archivos a esta guía.

### 3. La configuración requerida en PIXI aparece demasiado tarde — Alta

**Dónde:** INIT y opciones de paleta, líneas 78–208; «No reservar un Extra Byte», línea 546.

**Duda:** «El INIT lee ExtraByte1 y el extra bit: ¿qué debo declarar en el JSON y qué escribo en Lunar Magic?». El requisito del Extra Byte se presenta como error común al final, después de utilizarlo en los ejemplos.

**Recomendación:** mover la configuración necesaria antes del INIT. Mostrar una combinación de versión, modo y paleta con su byte hexadecimal resultante y dónde introducirlo. Explicar qué ocurre si una versión selecciona una entrada que no existe en la lista de paletas.

**Resolución:** aplicada en la sección de carga de paletas, según lo indicado por el autor. Se añadió el requisito de configurar al menos un Extra Byte en el CFG/JSON de un sprite normal para utilizar la asignación de paletas. Se explicó el uso de Extra Byte 1 para `PaletteOption` y `Version`, y de los bits 5 y 4 de Extra Property Byte 2 para `PaletteAssignmentOption`, con los tres modos y sus valores. Se conservó la advertencia de errores comunes. No se añadió un tutorial de configuración de PIXI ni Lunar Magic.

### 4. El orden de aprendizaje introduce símbolos antes de enseñar de dónde salen — Media

**Dónde:** RenderBox y manejo de paletas/poses.

**Duda:** «Todavía no he definido las poses, pero ya debo usar sus distancias e IDs generados. ¿En qué momento existen estos nombres?». Se repite muchas veces la normalización del nombre, pero falta un ejemplo que conecte nombre de archivo, nombre de pose y símbolo final.

**Recomendación:** preparar primero los archivos y ejecutar la generación. Después presentar una tabla única con cada símbolo del tutorial y su origen exacto. Mantener la advertencia de consultar DXDefines, pero reducir la repetición de PascalCase en cada sección.

**Resolución:** aplicada parcialmente según el acuerdo con el autor. No existía una tabla de origen de los defines en la guía, por lo que se añadió después de la explicación de los archivos y antes de la estructura del sprite. Resume los defines de distancias, tabla de paletas, poses dinámicas, poses de dibujo y efectos, con su origen y uso. Se conservaron las aclaraciones repetidas sobre origen, normalización y consulta de `DXDefines.asm` junto a cada uso: el autor considera que ayudan a evitar errores frecuentes sin obligar al lector a recordar otra sección. No se reorganizó el proceso de aprendizaje.

### 5. Los fragmentos requieren un contrato común de registros y retorno — Alta

**Dónde:** INIT, PaletteManagement y concatenación, líneas 82–112 y 303–348.

**Duda:** «¿En qué tamaño entran A, X e Y? Después de copiar la paleta a X, ¿cómo recupera la siguiente rutina el índice del sprite? ¿Qué banco permite leer PaletteEffects?». La guía explica conservar Y, pero no ofrece un contrato igualmente explícito para X, DBR y el estado de salida de todas las llamadas.

**Recomendación:** anteponer requisitos comunes y anotar los cambios especiales junto a cada ejemplo. Explicar qué llamadas recuperan el índice desde el contexto de PIXI y cuáles requieren que el llamador lo prepare. No afirmar que existe un fallo de implementación: la carencia comprobada es que el lector no puede deducir el contrato completo del tutorial.

**Resolución:** aplicada mediante referencias a la API, según la propuesta del autor. Se añadió una referencia general para dudas sobre registros, parámetros y resultados, y enlaces directos desde los apartados correspondientes a RenderBox, asignación de paletas, concatenación de efectos, carga de poses y dibujo. No se añadió una sección de contratos de registros a la guía ni se modificaron los ejemplos en este punto.

### 6. La regla «solo cambió el ASM» omite los comentarios de inclusión — Alta

**Dónde:** «Instalar y probar el sprite», línea 520.

**Duda:** «Si añado un ;#incdyn al ASM, ¿basta ejecutar PIXI?». La misma guía enseña que esos comentarios permiten que Dynamic Xtreme descubra recursos.

**Recomendación:** limitar la excepción a cambios de lógica que no alteren declaraciones o selección de recursos. Enumerar como cambios que requieren regeneración los includes especiales y las listas utilizadas para descubrirlos. Unificar la regla con el Quick Start.

**Resolución:** aplicada en ambos artículos por indicación del autor. La guía de sprites y Quick Start ahora indican que añadir, eliminar o modificar `;#incdyn`, `;#incdri` o `;#incpale` requiere reinstalar Dynamic Xtreme y después las herramientas consumidoras. Se aclaró que modificar solo el código ASM evita la reinstalación de Dynamic Xtreme únicamente si no se alteran esos includes.

### 7. Sumar una paleta no especifica qué sucede en el extremo del rango — Media

**Dónde:** PaletteAssignmentOption, línea 206: sumar `$10` para seleccionar la paleta siguiente.

**Duda:** «¿Qué hago si el sprite principal ya usa la F? ¿Podría cambiar el bit del efecto al sumar?». No se indica condición de validez ni destino alternativo.

**Recomendación:** declarar el rango en que se permite avanzar y el comportamiento que debe elegir el autor al alcanzar la última paleta. Añadir un ejemplo dentro del rango y otro que requiera una elección explícita, sin suponer que existe un retorno automático al principio.

**Resolución:** aplicada con la restricción indicada por el autor. Cuando el sprite generado utiliza una paleta distinta seleccionada sumando `$10`, y el principal emplea asignación manual o manual sin carga, el sprite principal no puede utilizar la paleta F. Se indicó que debe configurarse entre la 8 y la E. No se propuso un retorno automático al comienzo del rango ni una selección alternativa en tiempo de ejecución. La review de esta guía queda completada.

## Primer cambio recomendado

Resolver la contradicción del flujo y construir un ejemplo mínimo completo. Son mejoras previas a ampliar los casos avanzados.

es/Dynamic Xtreme files and formats

2026-10-25T16:41:36Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_files_and_formats}}

Dynamic Xtreme utiliza un sistema de archivos propio y bien estructurado que permite al usuario tener un control preciso y flexible sobre los recursos, efectos y datos que se usan durante la ejecución del juego.

Esta página documenta los diferentes tipos de archivos que maneja la herramienta, cómo funcionan, su propósito y los formatos específicos que utilizan (tanto los actuales como los legacy). Entender esta estructura es fundamental para aprovechar al máximo las capacidades de Dynamic Xtreme.

Muchos de los formatos legacy presentes en Dynamic Xtreme provienen originalmente de Dynamic X, la versión antigua sobre la cual evolucionó el proyecto. Estos formatos continúan siendo totalmente compatibles con el objetivo de mantener soporte para una gran cantidad de recursos ya existentes desarrollados para Dynamic X.

A continuación se detallan los principales tipos de archivos y sus formatos:

== Tipos de Archivos ==

Dynamic Xtreme utiliza varios tipos de archivos especializados. A continuación se describen los principales:

* '''Recursos Dinámicos''': Son recursos que se guardan en el ROM de forma descomprimida. Normalmente se usan para sprites dinámicos, cambios de gráficos, cambios de tilemaps o cambios de paletas.
* '''Palette Effects (*.paleffect):''' Son archivos utilizados para registrar efectos de paletas de colores.
* '''Dynamic Info (*.dynamicinfo):''' Son archivos que se usan para incluir recursos dinámicos en el ROM y también generar la data relevante para los sprites dinámicos.
* '''Draw Info (*.drawinfo):''' Son archivos utilizados para generar las poses (cuadros de animación) para los sprites y luego poder dibujarlas en pantalla.

== Inclusión de archivos desde PIXI y UberASMTool ==

Los recursos de PIXI y UberASMTool pueden declarar los archivos que
utilizan mediante comentarios especiales dentro de su ASM principal:

<pre>
;#incdyn "ruta/al/recurso.dynamicinfo"
;#incdri "ruta/al/recurso.drawinfo"
;#incpale "ruta/al/recurso.paleffect"
</pre>

Cada directiva registra un tipo de archivo diferente:

* <code>;#incdyn</code> incluye un archivo <code>*.dynamicinfo</code>.
* <code>;#incdri</code> incluye un archivo <code>*.drawinfo</code>.
* <code>;#incpale</code> incluye un archivo <code>*.paleffect</code>.

Las rutas son relativas al ASM principal que contiene la directiva.
Los archivos incluidos pueden encontrarse en la misma carpeta o en
cualquiera de sus subcarpetas.

Dynamic Xtreme busca estas directivas únicamente en los ASM
principales registrados en las listas de PIXI y UberASMTool. No sigue
archivos cargados mediante <code>incsrc</code>.

Los recursos internos de un <code>*.dynamicinfo</code> o
<code>*.paleffect</code> incluido de esta forma utilizan como base la
carpeta donde se encuentra su archivo de definición.

== Recursos Dinámicos ==

Los Recursos Dinámicos son uno de los sistemas centrales de Dynamic Xtreme. Estos recursos se almacenan en el ROM de forma descomprimida, lo que permite cargarlos y utilizarlos rápidamente durante la ejecución del juego.

=== ¿Cómo funciona el sistema? ===

Dynamic Xtreme recopila todos los recursos dinámicos, los organiza en paquetes de máximo 1 bank (32 O 64 KB) y los inserta automáticamente en el ROM. Si el ROM tiene hi-banks disponibles, el tool prioriza estos bancos para la inserción, mejorando la organización del espacio.

No existe una limitación estricta sobre el tipo de datos que se pueden insertar, aunque la mayoría de los archivos suelen ser de tipo '''"*.bin"'''.

=== Usos principales ===

Los recursos dinámicos se utilizan comúnmente para:
* '''Gráficos:''' Gráficos de sprites dinámicos o reemplazos gráficos en tiempo real.
* '''Tilemaps:''' Reemplazar tiles de los diferentes layers del nivel.
* '''Paletas de colores:''' Reemplazar paletas completas o asignar paletas específicas a sprites dinámicos.
* '''Otros''': Cualquier tipo de información que se desee almacenar en el ROM, como muestras de audio .brr, tablas de datos, etc.

Esto hace que el sistema sea extremadamente flexible, permitiendo no solo usos gráficos sino también cualquier otro tipo de dato que el usuario necesite tener disponible en el ROM de forma rápida.

=== Archivos de Paletas de colores ===

Actualmente, la mejor forma de guardar archivos de paletas de colores es utilizando archivos binarios ('''*.bin''') donde cada color ocupa 2 bytes siguiendo el formato de color utilizado por el SNES. Existen herramientas que facilitan este proceso, como [https://www.smwcentral.net/?p=section&a=details&id=24827 Pal2Bin].

Para entender esto, es importante considerar que el formato de color del SNES es BGR555. Esto significa que cada color se almacena utilizando 5 bits para azul, 5 bits para verde y 5 bits para rojo.

Conceptualmente, los bits se organizan así:

<code>-BBBBB GGGGG RRRRR</code>

Sin embargo, debido al endian utilizado por el SNES, los bytes deben almacenarse invertidos en memoria, por lo que internamente terminan organizados así:

<code>GGG RRRRR -BBBBB GG</code>

Debido a que este formato puede resultar confuso para usuarios no familiarizados con hardware del SNES, a futuro se planea incorporar soporte mejorado para archivos '''*.pal''', los cuales son mucho más conocidos y utilizados en herramientas gráficas modernas.

En el caso de las paletas utilizadas por sprites dinámicos, estas deben contener un máximo de 15 colores. Esto significa que únicamente deben incluirse los colores 1 al 15 de la paleta correspondiente, ya que el color 0 es utilizado como transparencia.

=== Gráficos para sprites dinámicos ===

Los gráficos de un sprite dinámico se dividen en poses. Cada pose contiene
los tiles que deben cargarse en VRAM para mostrar un cuadro de animación.

Dynamic Xtreme admite dos formas de organizar estos gráficos:

* El '''formato actual''', recomendado para recursos nuevos.
* El '''formato legacy''', conservado para mantener compatibilidad con
recursos creados para Dynamic X.

Ambos formatos producen el mismo resultado dentro del juego. La diferencia
se encuentra únicamente en cómo deben organizarse los gráficos dentro del
archivo.

==== Formato actual ====

En el formato actual, los gráficos se organizan utilizando espacios de
16x16 píxeles.

Los tiles de cada pose se colocan de forma consecutiva. Después de los
gráficos de una pose comienzan los gráficos de la siguiente.

El autor decide el orden de los tiles de cada pose en el archivo de gráficos. El DynamicInfo indica cuántos tiles pertenecen a cada pose, y el DrawInfo indica dónde se dibuja cada uno. Ambos deben corresponder con la organización de los gráficos.

Por ejemplo, una pose de 32x32 píxeles normalmente utiliza cuatro tiles de
16x16:

[[File:imagen 2026-05-17 221817296.png|thumb]]

La cantidad de tiles utilizada por cada pose se declara dentro del archivo
<code>*.dynamicinfo</code> mediante
<code>NumberOf16x16TilesPerPose</code>.

Dynamic Xtreme reorganiza automáticamente estos gráficos al formato interno
utilizado para realizar las transferencias DMA. Por esta razón, el autor del
recurso no necesita preparar manualmente el layout utilizado en VRAM.

Este es el formato recomendado para crear recursos nuevos.

Si el último tile de 16×16 solo se utiliza parcialmente, puedes indicar qué partes conservar mediante <code>q</code>, <code>h</code> o <code>q3</code>. Los gráficos se preparan con el espacio completo de 16×16; Dynamic Xtreme conserva las partes indicadas y descarta las restantes al procesar el recurso.

Cada celda de las siguientes tablas representa un tile de 8×8. La tabla completa representa el último tile de 16×16 de la pose. El verde indica las partes utilizadas y el gris las que se descartan.

===== q =====

{| class="wikitable"
! !! Mitad izquierda !! Mitad derecha
|-
! Mitad superior
| style="background-color:#d5f5dc; color:#202122;" | Tile de 8×8 superior izquierdo: usado
| style="background-color:#eaecf0; color:#202122;" | Tile de 8×8 superior derecho: no utilizado
|-
! Mitad inferior
| style="background-color:#eaecf0; color:#202122;" | Tile de 8×8 inferior izquierdo: no utilizado
| style="background-color:#eaecf0; color:#202122;" | Tile de 8×8 inferior derecho: no utilizado
|}

===== h =====

{| class="wikitable"
! !! Mitad izquierda !! Mitad derecha
|-
! Mitad superior
| style="background-color:#d5f5dc; color:#202122;" | Tile de 8×8 superior izquierdo: usado
| style="background-color:#d5f5dc; color:#202122;" | Tile de 8×8 superior derecho: usado
|-
! Mitad inferior
| style="background-color:#eaecf0; color:#202122;" | Tile de 8×8 inferior izquierdo: no utilizado
| style="background-color:#eaecf0; color:#202122;" | Tile de 8×8 inferior derecho: no utilizado
|}

===== q3 =====

{| class="wikitable"
! !! Mitad izquierda !! Mitad derecha
|-
! Mitad superior
| style="background-color:#d5f5dc; color:#202122;" | Tile de 8×8 superior izquierdo: usado
| style="background-color:#d5f5dc; color:#202122;" | Tile de 8×8 superior derecho: usado
|-
! Mitad inferior
| style="background-color:#d5f5dc; color:#202122;" | Tile de 8×8 inferior izquierdo: usado
| style="background-color:#eaecf0; color:#202122;" | Tile de 8×8 inferior derecho: no utilizado
|}

==== Formato legacy ====

El formato legacy requiere que los gráficos ya se encuentren organizados
según los bloques que serán transferidos mediante DMA.

Para una pose que utiliza siete tiles de 16x16 o menos, cada tile debe
separarse en dos mitades de 16x8. Primero se almacenan todas las mitades
superiores y después todas las mitades inferiores.

Por ejemplo, una pose formada por cuatro tiles:

<code>t1 t2 t3 t4</code>

debe almacenarse de esta manera:

<code>t1th t2th t3th t4th t1bh t2bh t3bh t4bh</code>

Donde:

* <code>th</code> representa la mitad superior del tile.
* <code>bh</code> representa la mitad inferior del tile.

Cuando una pose contiene ocho tiles de 16x16 o más, cada fila completa de
ocho tiles puede almacenarse directamente. Los tiles restantes se organizan
utilizando el sistema de mitades explicado anteriormente.

La distribución de cada pose se declara mediante
<code>PosesChunksSizes</code> dentro del archivo
<code>*.dynamicinfo</code>.

Este formato ofrece control directo sobre la organización interna, pero es
más difícil de preparar y mantener. Se recomienda principalmente para
recursos antiguos o casos avanzados.

== Efectos de Paletas ==

Los archivos de Efectos de paletas se almacenan dentro de la carpeta PaletteEffects y utilizan la extensión '''"*.paleffect"'''.

Los efectos de paleta permiten realizar modificaciones de colores en tiempo real sobre las paletas utilizadas por el juego. Estos efectos pueden ser utilizados por el sistema global de efectos de paleta de Dynamic Xtreme.

El efecto global afecta a todos los colores de cada paleta habilitada para recibirlo. Del mismo modo, un efecto aplicado a un sprite completo afecta a toda la paleta del sprite. Estos sistemas no permiten seleccionar colores individuales dentro de una paleta.

Si necesitas aplicar un efecto solo a colores específicos, debes hacerlo manualmente mediante las macros y rutinas descritas en la [[es/Dynamic_Xtreme_ASM_API|API ASM de Dynamic Xtreme]].

Internamente, estos sistemas funcionan modificando los canales '''RGB''' o '''HSL''' de los colores de la paleta para producir distintos efectos visuales.

Algunos usos comunes incluyen:

* Transiciones de día a noche.
* Flashes rojos para indicar peligro.
* Efectos cyan intermitentes para objetos a punto de explotar.
* Cambios de tinte para efectos tipo discoteca.
* Transiciones suaves entre estados visuales.
* Efectos de iluminación o ambientación.

El sistema permite una gran cantidad de combinaciones y efectos distintos.

=== Tipos de efectos ===

Actualmente existen los siguientes efectos:
<ul>
<li>'''MixRGB (ID 0)''': Interpola los canales '''RGB''' con un color base.</li>
<li>'''MixHSL (ID 1)''': Interpola los canales '''HSL''' con un color base.</li>
<li>'''MixRG (ID 2)''': Interpola únicamente '''R''' y '''G'''.</li>
<li>'''MixHS (ID 3)''': Interpola únicamente '''H''' y '''S'''.</li>
<li>'''MixRB (ID 4)''': Interpola únicamente '''R''' y '''B'''.</li>
<li>'''MixHL (ID 5)''': Interpola únicamente '''H''' y '''L'''.</li>
<li>'''MixGB (ID 6)''': Interpola únicamente '''G''' y '''B'''.</li>
<li>'''MixSL (ID 7)''': Interpola únicamente '''S''' y '''L'''.</li>
<li>'''MixR (ID 8)''': Interpola únicamente el canal '''R'''.</li>
<li>'''MixH (ID 9)''': Interpola únicamente el canal '''H'''.</li>
<li>'''MixG (ID 10)''': Interpola únicamente el canal '''G'''.</li>
<li>'''MixS (ID 11)''': Interpola únicamente el canal '''S'''.</li>
<li>'''MixB (ID 12)''': Interpola únicamente el canal '''B'''.</li>
<li>'''MixL (ID 13)''': Interpola únicamente el canal '''L'''.</li>
<li>'''PalTransitionRGB (ID 14)''': Interpola una paleta completa hacia otra utilizando canales '''RGB'''.</li>
<li>'''PalTransitionHSL (ID 15)''': Interpola una paleta completa hacia otra utilizando canales '''HSL'''.</li>
<li>'''PalFunctionRGB (ID 16)''': Aplica una transformación lineal sobre los canales '''RGB''':

* R = R11*R + R12*G + R13*B
* G = R21*R + R22*G + R23*B
* B = R31*R + R32*G + R33*B

Donde:

* RXY Son ratios
* R Corresponde al canal rojo
* G Corresponde al canal verde
* B Corresponde al canal azul

'''Nota:''' Este efecto aún no se encuentra implementado.
</li>

<li>'''PalFunctionHSL (ID 17)''': Aplica una transformación lineal sobre los canales '''HSL''':

* H = R11*H + R12*S + R13*L
* S = R21*H + R22*S + R23*L
* L = R31*H + R32*S + R33*L

Donde:

* '''RXY''' Son ratios.
* '''H''' Corresponde al tinte ('''Hue''').
* '''S''' Corresponde a la saturación.
* '''L''' Corresponde al brillo ('''Lightness''').

'''Nota:''' Este efecto aún no se encuentra implementado.
</li>
</ul>

==== Formato de archivos ====

Los efectos de paleta utilizan un formato basado en JSON:

<pre>
{
"Effects": []
}
</pre>

Donde:

* '''Effects''': Contiene la lista de efectos utilizados.

===== Formato simple =====

El formato simple define un único efecto:

<pre>
{
"Channel1": 31,
"Channel2": 0,
"Channel3": 0,
"Ratio1": 64,
"Ratio2": 64,
"Ratio3": 64,
"EffectType": 0
}
</pre>

Donde:

<ul>
<li>'''Channel1''', '''Channel2''', '''Channel3''' corresponden a los valores de canales principales
<ul>
<li>En efectos '''RGB''':
<ul>
<li>1 = R</li>
<li>2 = G</li>
<li>3 = B</li>
</ul>
<li>En efectos '''HSL''':
<ul>
<li>1 = H</li>
<li>2 = S</li>
<li>3 = L</li>
</ul>
</ul>
</li>
<li>'''Ratio1''', '''Ratio2''' y '''Ratio3''' son factores de interpolación: se utilizan para calcular cuánto influye el efecto en cada canal. Sus valores van de 0 (influencia mínima) a 127 (influencia máxima).</li>
<li>'''EffectType''' corresponde al ID del efecto utilizado.</li>
</ul>

Por ejemplo, el <code>MixRGB</code> anterior mezcla los colores originales con rojo: <code>Channel1 = 31</code>, <code>Channel2 = 0</code> y <code>Channel3 = 0</code>. Con los tres ratios en 64, el resultado queda aproximadamente a mitad de camino entre cada color original y ese rojo. Así, un color negro se convierte en un rojo de intensidad media. Al aumentar los ratios, el resultado se acerca más al rojo indicado.

===== Transiciones de paleta =====

Los efectos <code>PalTransitionRGB</code> y
<code>PalTransitionHSL</code> permiten interpolar los colores de una
paleta hacia otra.

A diferencia de los efectos de mezcla normales, estos efectos utilizan
el campo <code>Palette</code> para indicar la paleta objetivo:

<pre>
{
"Palette": "Palettes/NightPalette.bin",
"Ratio1": 64,
"Ratio2": 64,
"Ratio3": 64,
"EffectType": 14
}
</pre>

En este ejemplo se utiliza <code>PalTransitionRGB</code>, cuyo ID es
<code>14</code>. Para realizar la transición en HSL debe utilizarse
<code>PalTransitionHSL</code>, cuyo ID es <code>15</code>.

El archivo indicado en <code>Palette</code> debe contener colores
BGR555 de 2 bytes. Dynamic Xtreme convierte automáticamente la paleta
al formato interno requerido por el efecto RGB o HSL.

Los valores <code>Ratio1</code>, <code>Ratio2</code> y
<code>Ratio3</code> controlan la interpolación de sus respectivos
canales y deben encontrarse entre 0 y 127.

Cuando el archivo <code>*.paleffect</code> se encuentra en la carpeta
tradicional <code>PaletteEffects</code>, la ruta de
<code>Palette</code> se resuelve desde
<code>DynamicResources</code>.

Cuando el efecto se incluye desde PIXI o UberASMTool mediante
<code>;#incpale</code>, la ruta se resuelve desde la carpeta donde se
encuentra el archivo <code>*.paleffect</code>.

==== Rangos de valores ====

* Los valores de canales ('''Channel''') utilizan rangos entre '''0''' y '''31'''.
* Los valores de ratios ('''Ratio''') utilizan rangos entre '''0''' y '''127'''.

== DynamicInfo ==

Los archivos '''DynamicInfo''' se almacenan dentro de la carpeta '''DynamicInfos''' y utilizan la extensión '''*.dynamicinfo'''.

Estos archivos tienen 2 funciones principales:

* Incluir recursos dinámicos dentro del ROM.
* Definir qué gráficos corresponden a sprites dinámicos y cómo debe cargarse cada pose.

La estructura básica de un archivo `DynamicInfo` es la siguiente:

<pre>
PosesGraphics:
MyGraphics.bin
AnotherGraphics.bin

Palettes:
MyPal.bin
AnotherPal.bin

Resources:
MyResource.bin
AnotherResource.bin
</pre>

Estas secciones funcionan como listas de recursos dinámicos que serán incluidos por Dynamic Xtreme.

La base de las rutas depende de cómo se registre el archivo DynamicInfo:

{| class="wikitable"
! Método !! Desde dónde se buscan los archivos de PosesGraphics, Palettes y Resources
|-
| Carpetas tradicionales: DynamicInfo dentro de <code>DynamicInfos</code>
| Las rutas son relativas a la carpeta <code>DynamicResources</code>, junto al ejecutable de Dynamic Xtreme.
|-
| Inclusión mediante <code>;#incdyn</code>
| Las rutas son relativas a la carpeta donde se encuentra el archivo <code>*.dynamicinfo</code> incluido.
|}

Por ejemplo, en el método tradicional, <code>Graficos/MyGraphics.bin</code> se busca en <code>DynamicResources/Graficos/MyGraphics.bin</code>, no junto al DynamicInfo.

* '''PosesGraphics''' contiene archivos gráficos para sprites dinámicos. Estos deben utilizar formato '''*.bin'''.
* '''Palettes''' contiene archivos de paletas de colores. Actualmente utilizan formato '''*.bin''', aunque a futuro se planea agregar soporte para archivos '''*.pal'''.
* '''Resources''' permite incluir recursos dinámicos arbitrarios y no posee restricciones específicas de formato.

En el caso de PosesGraphics, cuando se utilizan múltiples archivos gráficos, todos ellos son combinados internamente en un único gran bloque de gráficos siguiendo el orden en el que fueron declarados.

Posteriormente, cada pose es recortada desde esa data combinada y almacenada dentro del ROM de la forma más conveniente posible para el sistema dinámico.

Debido a esto, no existe una diferencia práctica importante entre:

* Utilizar un único archivo grande de gráficos.
* Utilizar múltiples archivos pequeños separados.

Ambos enfoques producirán el mismo resultado interno dentro de Dynamic Xtreme.

Además de estas listas de recursos, los archivos '''DynamicInfo''' también contienen la definición de las poses dinámicas utilizadas por el sprite.

La forma en la que estas poses son definidas depende del formato utilizado por el recurso:

* Formato actual ('''NumberOf16x16TilesPerPose''').
* Formato legacy ('''PosesChunksSizes''').

=== Formato Actual ===

El formato moderno fue diseñado para simplificar la creación y mantenimiento de sprites dinámicos.

En este formato, el usuario únicamente necesita indicar cuántos tiles de 16x16 utiliza cada pose. Dynamic Xtreme se encarga automáticamente de procesar los gráficos y convertirlos internamente al formato optimizado utilizado por el sistema dinámico.

Ejemplo:

<pre>
NumberOf16x16TilesPerPose:
.Pose0 5
.Pose1 7h
.Pose2..6 4
</pre>

En este ejemplo:

* Pose0 utiliza 5 tiles de 16x16.
* Pose1 utiliza 7 tiles de 16x16 y adicionalmente una mitad superior (16x8).
* Pose2 hasta Pose6 utilizan 4 tiles de 16x16.

El formato también permite utilizar modificadores para representar tiles parciales:

* '''q''': Tile 8x8 superior izquierdo.
* '''h''': Mitad superior (16x8).
* '''q3''': Mitad superior + tile inferior izquierdo (16x8 + 8x8).

De este modo es posible incluir un tile de 16x16 que contenga gráficos de manera parcial. Estos tiles parciales no permiten todas las combinaciones posibles, debido a que muchas de ellas no son prácticas para el sistema. Únicamente se consideran las configuraciones más comunes y útiles.

Internamente, Dynamic Xtreme transforma automáticamente este formato al formato legacy, ya que dicho formato se encuentra optimizado para realizar transferencias DMA hacia VRAM de manera más eficiente.

=== Formato Legacy ===

El formato legacy utiliza una tabla llamada PosesChunksSizes, la cual define manualmente cómo deben organizarse los gráficos dinámicos internamente.

Ejemplo:

<pre>
PosesChunksSizes:
Pose0_PoseChunksSizes:
db $02,$02
Pose1_PoseChunksSizes:
db $02,$02
</pre>

Cada pose posee una subtabla compuesta por 2 valores.

La idea detrás de estos valores es representar cuántas rutinas DMA serían necesarias para transferir los gráficos de la pose hacia VRAM en condiciones ideales, es decir, asumiendo que el sprite se encuentra alineado al inicio de la sección de sprites de VRAM. En la práctica, en condiciones ideales se necesita 1 o 2 rutinas DMA.

La mayoría de las veces, la primera rutina DMA transfiere una cantidad mayor de datos que la segunda.

Cada uno de los 2 valores representa la cantidad de tiles de 8x8 transferidos por cada rutina DMA.

Por ejemplo:

<pre>
db $02,$02
</pre>

Significa:

* la primera rutina DMA transfiere 2 tiles de 8x8
* la segunda rutina DMA transfiere otros 2 tiles de 8x8

En casos especiales donde el sprite utiliza una cantidad de tiles de 16x16 que completa filas exactas dentro de VRAM (por ejemplo múltiplos de 8 tiles de 16x16), es posible realizar toda la transferencia utilizando una sola rutina DMA. En esos casos, el segundo valor se define como $00.

Este formato fue reemplazado por el formato actual debido a que resultaba complejo y poco intuitivo para la mayoría de usuarios. Actualmente se recomienda utilizar NumberOf16x16TilesPerPose, aunque el legacy continúa siendo totalmente compatible y sigue ofreciendo mayor flexibilidad para casos avanzados.

== DrawInfo ==

Los archivos DrawInfo se almacenan dentro de la carpeta DrawInfos y utilizan la extensión '''"*.drawinfo"''' y contienen la información necesaria para dibujar poses en pantalla.

Internamente, Dynamic Xtreme recopila esta información y genera rutinas gráficas optimizadas automáticamente. Cada rutina gráfica agrupa múltiples poses que comparten características similares y es optimizada específicamente para ese tipo de poses. Esto permite no solo un sistema global de renderizado de poses, sino también un sistema bastante eficiente en una gran cantidad de casos.

Para comprender cómo funcionan los archivos DrawInfo, es necesario entender a grandes rasgos cómo funciona la OAM del SNES.

La OAM es una memoria especial utilizada para almacenar información de sprites. En el caso del SMW, este trabaja utilizando tiles de 8x8 y 16x16.

Cada tile posee los siguientes atributos:

<ul>
<li>'''TileCode''': a veces llamado simplemente Tile, corresponde a un ID interno utilizado por la consola para indicar qué gráfico específico de VRAM debe utilizarse.
<br/>
'''Nota:''' Cuando se trabaja con sprites dinámicos, los TileCodes deben definirse asumiendo que el sprite fue cargado al inicio de la sección de sprites de VRAM.
<br/>
Dynamic Xtreme se encarga automáticamente de ajustar internamente estos valores dependiendo de la posición real donde la pose haya sido cargada en VRAM durante la ejecución.
</li>
<li>'''Properties''': corresponde a un byte con propiedades especiales del tile. Este byte utiliza el siguiente formato:
* '''YXCCPPPT'''
Donde:
<ul>
<li>'''Y''': indica si el tile se encuentra flippeado verticalmente.</li>
<li>'''X''': indica si el tile se encuentra flippeado horizontalmente.</li>
<li>'''CC''': prioridad del tile respecto a los layers (mayor valor = mayor prioridad).</li>
<li>'''PPP''': paleta de sprites utilizada (000 => palette 8, 001 => palette 9, ..., 111 => palette F).</li>
<li>'''T''': indica qué página gráfica utilizar (0 => SP12, 1 => SP34).</li>
</ul>

'''Nota:''' Es posible definir Properties generales para todos los tiles de una pose o sprite. Debido a esto, normalmente las properties más importantes dentro de los archivos DrawInfo son Y, X y T, mientras que las propiedades CC y PPP suelen configurarse desde el código que llama al sistema.

En el caso específico de sprites dinámicos, la property T normalmente no necesita ser configurada manualmente, ya que Dynamic Xtreme detecta automáticamente en qué página gráfica se encuentra la pose y configura este bit de forma automática.</li>
<li>'''Size''': define el tamaño del tile:
<ul>
<li>$00: tile pequeño (8x8).</li>
<li>$02: tile grande (16x16).</li>
</ul>
</li>
</ul>

Además, cada tile posee:

* X displacement (X Offset)
* Y displacement (Y Offset)

Estos valores permiten mover el tile respecto a la posición base del sprite.

Actualmente, Dynamic Xtreme posee 2 formatos DrawInfo: el formato actual y el formato legacy.

=== Formato Actual ===

El formato actual de DrawInfo fue diseñado para mejorar considerablemente la legibilidad y facilidad de mantenimiento de los archivos de dibujo.

A diferencia del formato legacy, este sistema permite:

* Agrupar múltiples poses.
* Agrupar rangos de tiles.
* Utilizar valores por defecto individuales.
* Omitir subtables innecesarias.
* Definir valores individuales o listas completas de valores.

Ejemplo:

<pre>
MyPose_Pose0..4:
.NumberOfTiles: 5
.TileCode2: $02
.TileCode3..4: $04
.Properties: $00,$40,$00,$00,$40
.XOffsets: $00,$10,$F8,$08,$18
.XPivot: $08
.YOffset2..4: $10
.YPivot: $10
.Size0..4: $02
</pre>

En este ejemplo:

* '''MyPose_Pose0..4''': Define información compartida para las poses 0 hasta 4 que comparten el nombre "MyPose".
* '''.NumberOfTiles''': Define que cada pose utiliza 5 tiles.
* '''.TileCode2''': Modifica el '''TileCode''' únicamente del tile 2.
* '''.TileCode3..4''': Modifica el '''TileCode''' de los tiles 3 y 4.
* '''.Properties''': Define una lista individual de '''Properties''' para cada tile.
* '''.XOffsets''': Define un '''XOffset''' individual para cada tile.
* '''.YOffset2..4''': Modifica el '''YOffset''' únicamente de los tiles 2 al 4.
* '''.Size0..4''': Define el tamaño de los tiles 0 al 4.

Los tiles se numeran desde 0. Por ejemplo, con <code>.NumberOfTiles: 5</code>, los tiles disponibles son del 0 al 4.

Las directivas utilizadas en singular permiten modificar un tile específico o un rango de tiles determinado.

Ejemplos:

<pre>
.TileCode2: $02
.TileCode3..4: $04
.YOffset1..3: $10
</pre>

En estos casos:

* '''.TileCode2:''': Modifica únicamente el tile 2
* '''.TileCode3..4''': Modifica únicamente los tiles 3 y 4
* '''.YOffset1..3''': Modifica el YOffset de los tiles 1 al 3

Por otro lado, las directivas en plural permiten definir explícitamente una lista completa de valores para todos los tiles de la pose.

Ejemplos:

<pre>
.Properties: $00,$40,$00,$00,$40
.XOffsets: $00,$10,$F8,$08,$18
</pre>

En estos casos:

* '''.Properties''': define una lista completa de Properties.
* '''.XOffsets''': define una lista completa de XOffsets.

Esto permite combinar configuraciones generales simples con modificaciones específicas únicamente donde sean necesarias.

Las declaraciones se aplican en el orden en que aparecen. Si varias modifican el mismo atributo de un tile, se utiliza el último valor indicado. Por ejemplo, después de <code>.Properties: $00,$40,$00,$00,$40</code>, puedes escribir <code>.Property2: $80</code> para cambiar únicamente la propiedad del tile 2 a <code>$80</code>. Si escribes la lista completa después, esa lista reemplazará los valores anteriores de todos los tiles.

Cuando un valor no es definido explícitamente, Dynamic Xtreme utiliza automáticamente valores por defecto:

* '''TileCode''': $00
* '''Property''': $00
* '''XOffset''': $00
* '''YOffset''': $00
* '''Size''': $02

A diferencia del formato legacy, estos valores por defecto funcionan de forma individual por tile, permitiendo omitir únicamente la información necesaria sin afectar el resto de la pose.

Los offsets indican dónde se coloca cada tile respecto a la posición del sprite, en píxeles. Sin volteo, se suma <code>XOffset</code> a la posición X del sprite y <code>YOffset</code> a su posición Y. Por ejemplo, un <code>XOffset</code> de <code>$10</code> coloca el tile 16 píxeles a la derecha; <code>$F8</code> representa −8 y lo coloca 8 píxeles a la izquierda.

Los valores '''XPivot''' y '''YPivot''' permiten calcular dónde deben colocarse los tiles al voltear toda la pose horizontal o verticalmente. No giran la pose: se utilizan para reflejar su distribución.

Para el volteo horizontal, el cálculo equivale a estos pasos:

# Se toma la posición X del sprite.
# Se le suma <code>XPivot</code>.
# Se resta el <code>XOffset</code> original del tile, para invertir su desplazamiento.
# Si el tile es de 16×16, se restan otros 8 píxeles para ajustar su posición según su tamaño. Para un tile de 8×8 no se hace este ajuste.

Por tanto, la posición X del tile volteado es:

* '''Tile de 8×8:''' <code>X del sprite + XPivot − XOffset</code>.
* '''Tile de 16×16:''' <code>X del sprite + XPivot − XOffset − 8</code>.

Por ejemplo, una pose tiene dos tiles de 16×16 con <code>XOffset</code> de 0 y 16. Si defines <code>.XPivot: $18</code> (24 en decimal), sus posiciones se intercambian al voltear la pose:

{| class="wikitable"
! Tile !! Sin volteo !! Con volteo horizontal
|-
| Primero: XOffset = 0
| X del sprite + 0
| X del sprite + 24 − 0 − 8 = X del sprite + 16
|-
| Segundo: XOffset = 16
| X del sprite + 16
| X del sprite + 24 − 16 − 8 = X del sprite + 0
|}

Para el volteo vertical se hace el mismo cálculo, usando la posición Y del sprite, <code>YPivot</code> y <code>YOffset</code>.

Estos desplazamientos para el volteo se calculan durante la instalación. Durante el juego, la rutina de dibujo utiliza los que corresponden al volteo solicitado.

Si '''XPivot''' no es definido, la pose no será considerada compatible con flip horizontal. Del mismo modo, si '''YPivot''' no es definido, la pose no será considerada compatible con flip vertical.

Esto permite que Dynamic Xtreme genere rutinas gráficas más optimizadas cuando estas características no son necesarias, además de reducir ligeramente el espacio utilizado dentro del ROM.

También es posible utilizar:

<pre>
.IsStatic
</pre>

Esto indica que las poses definidas deben considerarse poses estáticas en lugar de dinámicas. Por defecto, todas las poses son tratadas como dinámicas.

El formato legacy de DrawInfo continúa siendo totalmente compatible. El formato moderno existe principalmente para simplificar la escritura, lectura y mantenimiento de archivos DrawInfo, manteniendo al mismo tiempo un alto nivel de flexibilidad.

=== Formato Legacy ===

El formato legacy de DrawInfo utiliza múltiples tablas separadas para definir cada atributo de los tiles utilizados por una pose.

Este formato fue diseñado siguiendo una estructura similar a la utilizada normalmente al escribir rutinas gráficas manuales para sprites en SNES. La idea original era que las personas que ya estaban acostumbradas a desarrollar sprites de esta forma pudieran trabajar con DrawInfo utilizando una organización familiar y relativamente intuitiva para ese workflow tradicional.

Ejemplo:

<pre>
Dynamic:
true

Tiles:
MyPose0_Tiles:
db $00
MyPose1_Tiles:
db $00

Properties:
MyPose0_Properties:
db $00
MyPose1_Properties:
db $00

XDisplacements:
MyPose0_XDisp:
db $00
MyPose1_XDisp:
db $00
MyPose0_XDispFlip:
db $00
MyPose1_XDispFlip:
db $00

YDisplacements:
MyPose0_YDisp:
db $01
MyPose1_YDisp:
db $01
MyPose0_YDispFlip:
db $FF
MyPose1_YDispFlip:
db $FF

Sizes:
MyPose0_Sizes:
db $02
MyPose1_Sizes:
db $02
</pre>

En este formato:

* Cada atributo utiliza una sección independiente
* Cada pose requiere una subtabla separada
* Todos los valores deben escribirse manualmente
* No existen rangos de tiles ni agrupación de poses

Las tablas principales corresponden a:

* '''Tiles''': TileCodes
* '''Properties''': Properties de OAM
* '''XDisplacements''': Desplazamientos horizontales
* '''YDisplacements''': Desplazamientos verticales
* '''Sizes''': Tamaño de los tiles (8x8 o 16x16)

En el caso de XDisplacements y YDisplacements, también es posible definir versiones flippeadas:

* XDispFlip
* YDispFlip

Estas tablas permiten especificar manualmente los offsets utilizados cuando una pose es dibujada utilizando flip horizontal o vertical.

La directiva:

<pre>
Dynamic: true
</pre>

Indica que las poses deben ser tratadas como poses dinámicas. Si se define como false, las poses serán consideradas estáticas.

Al igual que en el formato moderno, existen valores por defecto automáticos. Si alguna tabla no existe, Dynamic Xtreme asumirá automáticamente los siguientes valores:

* '''TileCode''': $00
* '''Property''': $00
* '''XOffset''': $00
* '''YOffset''': $00
* '''Size''': $02

Este formato continúa siendo totalmente compatible con Dynamic Xtreme, aunque actualmente se recomienda utilizar el formato moderno debido a que resulta considerablemente más legible, mantenible y fácil de editar.

es/Dynamic Xtreme Quick Start

2026-10-25T07:20:48Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_Quick_Start}}

Esta guía explica cómo realizar una instalación básica de Dynamic
Xtreme en Windows o Linux.

Si es la primera vez que utilizas la herramienta, sigue los pasos en
el orden indicado. No es necesario conocer el funcionamiento interno
del sistema para completar la instalación.

== Requisitos ==

Dynamic Xtreme requiere el runtime de .NET 8. Descarga e instala la
versión correspondiente a tu sistema operativo desde el sitio oficial
de Microsoft:

[https://dotnet.microsoft.com/download/dotnet/8.0 .NET 8 Runtime]

La herramienta es compatible con Windows y Linux. Solo necesitas el
runtime de .NET; no es necesario instalar el SDK completo.

Puedes descargar Dynamic Xtreme desde SNEStorage: [https://snestorage.dev/Resource/7 SNEStorage - Dynamic Xtreme]

== Preparar los recursos ==

Antes de ejecutar Dynamic Xtreme, añade a tu proyecto todos los
recursos que deseas instalar.

=== Recursos para PIXI y UberASMTool ===

Los recursos actuales normalmente incluyen su archivo
<code>*.asm</code> o <code>*.json</code> junto con los archivos que
necesitan. Copia el paquete completo sin cambiar su estructura de
carpetas.

En PIXI, utiliza la carpeta correspondiente al tipo de sprite:

* <code>sprites</code> para sprites normales.
* <code>cluster</code> para cluster sprites.
* <code>extended</code> para extended sprites.
* Para otros tipos, utiliza la carpeta indicada por el recurso.

En UberASMTool, utiliza la carpeta correspondiente al tipo de código:

* <code>level</code> para códigos de nivel.
* <code>overworld</code> para códigos del overworld.
* <code>gamemode</code> para códigos de game mode.
* Para otros tipos, utiliza la carpeta indicada por el recurso.

Después de copiar el recurso, añádelo al archivo de lista de PIXI o
UberASMTool como lo harías normalmente.

Los recursos preparados para Dynamic Xtreme ya contienen las
declaraciones necesarias en su archivo ASM principal. Mantén juntos
el ASM, el JSON y las carpetas incluidas con el recurso para no romper
sus rutas relativas.

=== Carpetas tradicionales ===

Algunos recursos utilizan las carpetas tradicionales de Dynamic
Xtreme. En ese caso, sigue esta organización:

Estas carpetas se encuentran junto al ejecutable de Dynamic Xtreme: <code>dxt.exe</code> en Windows o <code>dxt</code> en Linux.

{| class="wikitable"
! Tipo de archivo
! Carpeta
|-
| <code>*.dynamicinfo</code>
| <code>DynamicInfos</code>
|-
| <code>*.drawinfo</code>
| <code>DrawInfos</code>
|-
| <code>*.paleffect</code>
| <code>PaletteEffects</code>
|-
| Gráficos, paletas y otros archivos relacionados
| <code>DynamicResources</code>
|}

Utiliza siempre el método indicado por el recurso. No muevas a las
carpetas tradicionales los archivos de un sprite o código UberASM
moderno, salvo que sus instrucciones lo soliciten.

== Instalación completa ==

=== Ejecutar la herramienta ===

Dynamic Xtreme debe ejecutarse desde su propia carpeta.

* En Windows, haz doble clic en <code>dxt.exe</code>.
* En Linux, abre una terminal en la carpeta de Dynamic Xtreme y ejecuta:

<pre>
./dxt
</pre>

La herramienta mostrará una serie de preguntas para configurar la
instalación.

=== Configurar las rutas ===

Las rutas y las funcionalidades seleccionadas quedan guardadas en <code>Settings/Settings.json</code>, dentro de la carpeta de Dynamic Xtreme. La herramienta utiliza ese archivo para recuperar la configuración en las siguientes instalaciones.

Puedes escribir cada ruta o arrastrar el archivo correspondiente a la
terminal. Después, presiona Enter para continuar.

Si dejas una respuesta vacía y presionas Enter, Dynamic Xtreme
utilizará el valor guardado en <code>Settings/Settings.json</code>. Si todavía no
existe un valor guardado y la ruta es opcional, esa integración se
omitirá.

Las rutas se solicitan en el siguiente orden:

# '''ROM de entrada'''
#: Selecciona la ROM de Super Mario World que deseas modificar.

# '''ROM de salida'''
#: Indica la ruta de la ROM que tendrá el resultado de la instalación.

# '''Ejecutable de PIXI'''
#: Selecciona el ejecutable de PIXI. Esta ruta permite integrar las
#: rutinas y definiciones de Dynamic Xtreme con PIXI.

# '''Ejecutable de UberASMTool'''
#: Selecciona el ejecutable de UberASMTool si tu proyecto utiliza
#: códigos de UberASM.

# '''Ejecutable de GPS'''
#: Selecciona el ejecutable de GPS si tu proyecto utiliza bloques
#: personalizados.

# '''Lista de PIXI'''
#: Selecciona el archivo de lista donde registraste los sprites que
#: utilizará tu proyecto.

# '''Lista de UberASMTool'''
#: Selecciona el archivo de lista donde registraste los códigos
#: UberASM que utilizará tu proyecto.

Las rutas de PIXI, UberASMTool, GPS y sus listas son opcionales.
Si no utilizas alguna de estas herramientas y no existe una ruta
guardada, puedes dejar la respuesta vacía.

Para dejar de utilizar una integración que ya tiene rutas guardadas, edita <code>Settings/Settings.json</code> y deja sus valores como cadenas vacías (<code>""</code>):

* PIXI: <code>PixiPath</code> y <code>PixiListPath</code>.
* UberASMTool: <code>UberasmToolPath</code> y <code>UberasmListPath</code>.
* GPS: <code>GPSPath</code>.

No elimines los campos ni reemplaces todo el archivo. En las siguientes preguntas podrás dejar esas rutas vacías sin recuperar la integración anterior.

=== Seleccionar las funciones ===

Después de configurar las rutas, Dynamic Xtreme preguntará qué
funciones deseas instalar.

Puedes responder <code>Y</code> para habilitar una función o
<code>N</code> para deshabilitarla.

Si presionas Enter sin escribir nada, se conservará el valor guardado
en <code>Settings/Settings.json</code>. Durante la primera instalación se utilizará
el valor predeterminado de la función.

En una instalación habitual se pueden habilitar las funciones que no
muestran advertencias. Si aparece una advertencia en rojo, léela con
atención y comprueba su compatibilidad con tu proyecto antes de
habilitar esa función.

Consulta [[es/Dynamic_Xtreme#Funcionalidades|Funcionalidades]] para saber qué hace cada opción y [[es/Dynamic_Xtreme#Compatibilidad|Compatibilidad]] para revisar los posibles conflictos con otros recursos y los espacios de RAM utilizados.

=== Ejemplo de instalación típica con PIXI y UberASMTool ===

Este ejemplo utiliza PIXI y UberASMTool con las opciones predeterminadas. Las rutas son ficticias y corresponden a Windows; sustitúyelas por las de tu proyecto. En Linux, indica las rutas de sus ejecutables correspondientes.

{| class="wikitable"
! Pregunta !! Ejemplo de respuesta
|-
| ROM de entrada || <code>C:\MiHack\MiHack.smc</code>
|-
| ROM de salida || <code>C:\MiHack\MiHack_DX.smc</code>
|-
| Ejecutable de PIXI || <code>C:\MiHack\PIXI\pixi.exe</code>
|-
| Ejecutable de UberASMTool || <code>C:\MiHack\UberASMTool\UberASMTool.exe</code>
|-
| Ejecutable de GPS || Dejar vacío si no se utiliza y no hay una ruta guardada.
|-
| Lista de PIXI || <code>C:\MiHack\PIXI\list.txt</code>
|-
| Lista de UberASMTool || <code>C:\MiHack\UberASMTool\list.txt</code>
|}

Para las funcionalidades, utiliza estos valores:

{| class="wikitable"
! Funcionalidad !! Activada !! Respuesta
|-
| <code>GraphicsChange</code> || Sí || <code>Y</code>
|-
| <code>PalettesChange</code> || Sí || <code>Y</code>
|-
| <code>DynamicPoses</code> || Sí || <code>Y</code>
|-
| <code>DrawingSystem</code> || Sí || <code>Y</code>
|-
| <code>PalettesEffects</code> || Sí || <code>Y</code>
|-
| <code>Free7E2000</code> || Sí || <code>Y</code>
|-
| <code>ControllerOptimization</code> || Sí || <code>Y</code>
|-
| <code>FixedColorOptimization</code> || Sí || <code>Y</code>
|-
| <code>KevinLMVRAMOptimization</code> || No || <code>N</code>
|-
| <code>StatusBarOptimization</code> || No || <code>N</code>
|-
| <code>PlayerFeatures</code> || No || <code>N</code>
|-
| <code>YoshiFeatures</code> || No || <code>N</code>
|}

En ROMs con SA-1, <code>Free7E2000</code> se desactiva automáticamente.

Enter conserva el valor guardado si ya utilizaste la herramienta. Para reproducir esta configuración, responde <code>Y</code> o <code>N</code> según la tabla; los valores predeterminados solo se utilizan cuando no hay una selección anterior.

== Instalación mediante línea de comandos ==

Después de completar una instalación interactiva, Dynamic Xtreme
guarda las rutas y funciones seleccionadas en
<code>Settings/Settings.json</code>.

Puedes reutilizar esa configuración para realizar instalaciones
posteriores sin responder nuevamente todas las preguntas.

En Windows, abre una terminal en la carpeta de Dynamic Xtreme y
ejecuta:

<pre>
.\dxt.exe -use-settings
</pre>

En Linux, ejecuta:

<pre>
./dxt -use-settings
</pre>

Si alguna ruta guardada ya no es válida, Dynamic Xtreme volverá al
modo interactivo para solicitar la configuración.

Las opciones disponibles son:

{| class="wikitable"
! Opción
! Alias
! Descripción
|-
| <code>-use-settings</code>
| <code>-us</code>
| Utiliza las rutas y funciones guardadas sin mostrar nuevamente las
preguntas.
|-
| <code>-verbose</code>
| <code>-v</code>
| Muestra información más detallada durante la instalación.
|-
| <code>-help</code>
|
| Muestra la ayuda y la lista de opciones disponibles.
|-
| <code>-version</code>
|
| Muestra la versión instalada de Dynamic Xtreme.
|}

Las opciones pueden combinarse. Por ejemplo, para utilizar la
configuración guardada y mostrar información detallada:

'''Windows:'''

<pre>
.\dxt.exe -use-settings -verbose
</pre>

'''Linux:'''

<pre>
./dxt -use-settings -verbose
</pre>

Para cambiar las rutas o las funciones seleccionadas, ejecuta Dynamic
Xtreme sin <code>-use-settings</code> y completa nuevamente las
preguntas.

== Finalizar la instalación ==

Tanto la instalación interactiva como la instalación mediante línea
de comandos producen el mismo resultado.

El resultado de la instalación queda guardado en <code>log.txt</code>, junto al ejecutable de Dynamic Xtreme. Este archivo contiene todos los detalles de la instalación.

Dynamic Xtreme prepara la integración con PIXI, UberASMTool y GPS,
pero no ejecuta estas herramientas. Después de instalar Dynamic
Xtreme, vuelve a ejecutar las herramientas externas que utilice tu
proyecto sobre la ROM de salida.

'''Cuándo reinstalar:'''

* Si cambias gráficos, paletas o archivos <code>*.dynamicinfo</code>, <code>*.drawinfo</code> o <code>*.paleffect</code>, reinstala Dynamic Xtreme y después las herramientas que utilicen esos recursos.
* Si solo modificas el <code>*.asm</code>, no necesitas reinstalar Dynamic Xtreme. Basta con volver a insertar el código con la herramienta correspondiente.

Cuando sea necesario reinstalar Dynamic Xtreme, el orden correcto es:

# Ejecutar Dynamic Xtreme para regenerar e instalar sus recursos.
# Volver a ejecutar PIXI, UberASMTool, GPS y cualquier otra
#: herramienta que utilice datos generados por Dynamic Xtreme.

Este orden es necesario porque las direcciones y los identificadores
de los recursos pueden cambiar cada vez que se ejecuta Dynamic
Xtreme.

es/Dynamic Xtreme

2026-10-25T07:04:48Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme}}

Dynamic Xtreme es una herramienta de soporte dinámico avanzada para Super Mario World en el SNES. Desarrollada para la comunidad de ROM hacking, permite realizar cambios gráficos y de paletas en tiempo real durante la ejecución del juego. La herramienta se centra en ofrecer un sistema completo y flexible de gráficos dinámicos, con énfasis en el rendimiento y la modularidad.

Un sprite dinámico carga recursos, como gráficos o paletas, en tiempo real durante el juego. En cambio, un sprite estático utiliza los recursos que ya estaban cargados al comenzar el nivel.

Dynamic Xtreme no rompe los límites del hardware de SNES: trabaja dentro de ellos y optimiza el uso de la memoria y las transferencias para reducir su impacto y hacer que sean mucho menos perceptibles durante el juego.

Entre sus características principales se incluyen:
* Cambios gráficos y de paleta en tiempo real (on-the-fly).
* El sistema de Dynamic Sprite más potente y flexible disponible para Super Mario World.
* Advanced Drawing System, que permite dibujar cualquier frame registrado en pantalla con control total sobre prioridad, capa, desplazamiento (offset) y propiedades.
* Efectos de paleta avanzados, que incluyen modificación en tiempo real mediante tono (hue), saturación, brillo, fusión de colores, transiciones suaves y control individual de canales RGB y HSL.
* Reemplazo completo de gráficos y paletas del jugador, compatible con cualquier tamaño de Mario, cualquier cantidad de frames y cualquier estilo de animación.
* Reemplazo de gráficos de Yoshi usando un layout como el del juego original.
* Optimizaciones intensivas en el NMI-handler para maximizar el rendimiento.

Las funciones de Dynamic Xtreme se seleccionan durante la instalación para utilizar solo las que necesita el proyecto. Algunas tienen dependencias, problemas de compatibilidad o restricciones para desinstalarlas; revisa las advertencias de cada opción. La herramienta fue creada con el objetivo de facilitar la implementación de efectos visuales complejos en hacks de Super Mario World manteniendo un alto nivel de compatibilidad y estabilidad.

== Objetivos del proyecto ==

El principal objetivo de Dynamic Xtreme es facilitar el uso de sprites dinámicos y ofrecer un soporte completo para cambios de gráficos, paletas y tilemaps en tiempo real.

El proyecto busca aprovechar al máximo el potencial del SNES sin requerir que el usuario tenga conocimientos avanzados sobre el hardware interno de la consola. Muchos sistemas dinámicos tradicionales suelen ser complejos y dependen fuertemente de conceptos técnicos como VRAM, CGRAM, OAM o DMA. Dynamic Xtreme intenta abstraer gran parte de esa complejidad mediante herramientas y formatos más modernos, legibles y fáciles de utilizar.

Otro de los objetivos principales del proyecto es mantener un alto rendimiento incluso en situaciones visualmente complejas, permitiendo el uso intensivo de gráficos dinámicos, efectos de paletas y sistemas avanzados de renderizado sin comprometer innecesariamente la performance.

Además, Dynamic Xtreme busca que los sprites dinámicos puedan utilizarse de una forma tan natural y sencilla como si fueran sprites normales. La idea es que las personas enfocadas en level design o creación de contenido no necesiten preocuparse constantemente por las limitaciones técnicas internas del sistema y puedan trabajar con recursos dinámicos de forma transparente y práctica.

== Funcionalidades ==

Durante la instalación puedes elegir qué funcionalidades habilitar. Los nombres entre paréntesis corresponden a las opciones del instalador y de <code>Settings.json</code>.

=== Gráficos, poses y paletas ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Cambios de gráficos (<code>GraphicsChange</code>) || Permite cargar gráficos durante el juego. Es la base para las animaciones de tiles, los cambios de gráficos del nivel y las poses dinámicas.
|-
| Cambios de paletas (<code>PalettesChange</code>) || Permite cargar y administrar paletas durante el juego. Incluye la asignación automática de paletas para que los sprites puedan compartir los mismos colores sin cargarlos varias veces.
|-
| Poses dinámicas (<code>DynamicPoses</code>) || Administra el espacio de VRAM como una caché de poses: reutiliza las que ya están cargadas, permite compartirlas entre entidades y elige cuáles reemplazar cuando hace falta espacio. Así evita cargas innecesarias.
|-
| Dibujo de poses (<code>DrawingSystem</code>) || Dibuja las poses definidas en archivos DrawInfo, tanto dinámicas como estáticas. Permite controlar sus tiles, posición, volteo, paleta y prioridad de dibujo.
|-
| Efectos de paleta (<code>PalettesEffects</code>) || Permite cambiar colores mediante efectos RGB y HSL: teñir paletas, modificar tono, saturación o luminosidad, y realizar transiciones entre paletas. Pueden aplicarse a recursos individuales o como un efecto global.
|}

La carga de poses dinámicas y el dibujo son sistemas separados: puedes dibujar una pose estática sin cargar sus gráficos dinámicamente.

=== Jugador y Yoshi ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Funciones del jugador (<code>PlayerFeatures</code>) || Permite cambiar los gráficos y paletas del jugador y adaptar su dibujo y carga de poses a sistemas personalizados. También permite ocultarlo o desactivar sus cargas dinámicas. Puede entrar en conflicto con parches que modifican los gráficos o paletas del jugador; revisa la advertencia del instalador antes de habilitarla.
|-
| Funciones de Yoshi (<code>YoshiFeatures</code>) || Permite cambiar los gráficos de Yoshi manteniendo la organización de sus poses originales. Requiere <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad.
|}

=== Memoria y optimizaciones ===

Estas opciones reorganizan parte del trabajo del juego para dejar más tiempo disponible para las cargas de gráficos y paletas. NMI es la rutina que realiza las actualizaciones de pantalla durante la pausa entre un frame y el siguiente.

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Liberar el área <code>$7E2000</code> (<code>Free7E2000</code>) || En ROMs sin SA-1, evita mantener en RAM ciertos gráficos originales del jugador, Yoshi y animaciones, y permite leerlos desde ROM. Dynamic Xtreme utiliza el espacio recuperado para sus variables internas; no queda libre para usarlo sin reservar. Esta opción no se aplica a ROMs con SA-1.
|-
| Optimización del control (<code>ControllerOptimization</code>) || Mueve el procesamiento del control fuera de NMI para dejar más tiempo disponible para las actualizaciones de pantalla.
|-
| Optimización del color fijo (<code>FixedColorOptimization</code>) || Reduce el trabajo de NMI relacionado con la actualización del color fijo que utiliza el juego para sus mezclas de color.
|-
| Optimización de VRAM de Lunar Magic de Kevin (<code>KevinLMVRAMOptimization</code>) || Integra la optimización de Kevin para las actualizaciones de VRAM de Lunar Magic y mueve parte de su procesamiento fuera de NMI. Utiliza esta versión en lugar del parche original por separado. Una vez instalada, no debe desinstalarse: hacerlo puede dañar el funcionamiento de la ROM.
|-
| Optimización de la barra de estado (<code>StatusBarOptimization</code>) || Reduce el trabajo de NMI de la barra de estado original. No es compatible con recursos que la reemplazan o modifican, como barras de estado personalizadas o parches que la eliminan.
|}

Para revisar qué opciones pueden entrar en conflicto con otros recursos y qué RAM utiliza el sistema, consulta [[#Compatibilidad|Compatibilidad]].

Algunas funcionalidades necesitan otras: <code>DynamicPoses</code> requiere <code>GraphicsChange</code>; <code>PalettesEffects</code> requiere <code>PalettesChange</code>; <code>PlayerFeatures</code> necesita ambas opciones de cambios gráficos y de paletas; y <code>YoshiFeatures</code> requiere <code>PlayerFeatures</code>.

== Quick Start ==

'''Guía rápida de instalación:''' [[es/Dynamic_Xtreme_Quick_Start|Quick Start]]

== Herramientas y Soporte ==

Pendiente

== Archivos y formatos ==

'''Artículo relacionado:''' [[es/Dynamic_Xtreme_files_and_formats|Archivos y Formatos de Dynamic Xtreme]]

== Guía de creación de sprites dinámicos ==

Para aprender a preparar, programar, cargar y dibujar un sprite dinámico, consulta la [[es/Dynamic_Xtreme_sprite_creation_guide|guía de creación de sprites dinámicos con Dynamic Xtreme]].

== Dynamic Xtreme con UberASM ==

La [[es/Dynamic_Xtreme_UberASM_guide|guía de Dynamic Xtreme con UberASM]] muestra cómo reservar paletas, configurar el espacio para sprites dinámicos y el límite de datos por frame, crear animaciones, cambiar gráficos del jugador y aplicar efectos de paleta.

== API ==

La [[es/Dynamic_Xtreme_ASM_API|referencia de la API ASM]] explica cómo utilizar las variables, los defines, las rutinas y las macros de Dynamic Xtreme. Incluye los datos que necesita cada llamada, sus resultados y ejemplos de uso para trabajar con poses, dibujo, paletas, efectos de color y transferencias de gráficos, además de las macros de multiplicación y división.

== Funcionamiento interno del sistema ==

El artículo sobre el [[es/Dynamic_Xtreme_internal_workings|funcionamiento interno de Dynamic Xtreme]] explica cómo se organizan NMI y los game modes, las cargas de gráficos y paletas, el dibujo de poses, las optimizaciones, la caché de poses dinámicas y los efectos de paleta.

== Compatibilidad ==

En general, las funcionalidades que no muestran warnings en el instalador no suelen presentar problemas de incompatibilidad con otros recursos. Estas son:

* <code>GraphicsChange</code>
* <code>PalettesChange</code>
* <code>DynamicPoses</code>
* <code>DrawingSystem</code>
* <code>PalettesEffects</code>
* <code>Free7E2000</code>
* <code>ControllerOptimization</code>
* <code>FixedColorOptimization</code>

Esto no garantiza que cualquier combinación de recursos funcione: dos códigos todavía pueden utilizar la misma RAM, el mismo espacio de VRAM o modificar la misma rutina del juego. Además, <code>YoshiFeatures</code> necesita <code>PlayerFeatures</code>, por lo que también debes considerar las restricciones de esta última.

=== Funcionalidades con restricciones de compatibilidad ===

{| class="wikitable"
! Funcionalidad opcional !! Posibles conflictos y qué hacer
|-
| <code>PlayerFeatures</code> || Puede entrar en conflicto con '''LX5's Powerups''', '''Player 8x8 tiles DMAer''', '''Player 32x32''' y otros sistemas que reemplazan la carga de gráficos o paletas del jugador. '''Player Revolution''' sí es compatible. Si tu sistema de jugador necesita esas rutinas originales, deja esta opción deshabilitada; también tendrás que deshabilitar <code>YoshiFeatures</code>.
|-
| <code>YoshiFeatures</code> || Depende de <code>PlayerFeatures</code> y hereda sus restricciones de compatibilidad, aunque no muestre un warning propio. Si otro recurso es incompatible con <code>PlayerFeatures</code>, no puedes evitar ese conflicto habilitando únicamente <code>YoshiFeatures</code>: debes dejar ambas deshabilitadas.
|-
| <code>StatusBarOptimization</code> || No es compatible con recursos que modifican, reemplazan o eliminan la barra de estado original, como '''LX5's DKC Style Status Bar''', '''Minimalistic Status Bar''' y '''Nuke Status Bar'''. Si utilizas uno de ellos, deja esta optimización deshabilitada.
|-
| <code>KevinLMVRAMOptimization</code> || Integra el parche de optimización de VRAM de Lunar Magic de Kevin: utiliza esta versión en lugar del parche original por separado. Su warning también indica que '''no debe desinstalarse después de instalarla''', porque hacerlo puede romper el funcionamiento de la ROM. Si necesitas revertirla, restaura una copia de seguridad anterior a su instalación.
|}

Estas funcionalidades son opcionales: puedes dejar deshabilitada la que entra en conflicto y seguir utilizando los demás sistemas de Dynamic Xtreme, respetando sus dependencias. Deshabilitar una opción no deshace los cambios de otro parche ni elimina la restricción de desinstalación de <code>KevinLMVRAMOptimization</code>.

=== Espacios de RAM utilizados ===

Las direcciones principales se configuran en <code>ASM/DXDefines.asm</code>, dentro de la carpeta de Dynamic Xtreme. En el repositorio, ese archivo corresponde a <code>DynamicXtremeLibrary/ASM/DXDefines.asm</code>.

El espacio utilizado depende de las funcionalidades habilitadas y de si la ROM utiliza SA-1. Los siguientes rangos incluyen el primer y el último byte y están calculados con '''todas las funcionalidades que reservan RAM habilitadas''', <code>!VRAMTransferSize = 64</code> y <code>!CGRAMTransferSize = 64</code>:

{| class="wikitable"
! Configuración !! Bloque <code>!Variables</code> !! Tamaño !! Bloque <code>!Variables2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2000–$7E2500</code> || <code>$0501</code>: 1281 bytes || <code>$7E2800–$7E3608</code> || <code>$0E09</code>: 3593 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB440–$7FB940</code> || <code>$0501</code>: 1281 bytes || <code>$7F9C80–$7FAA88</code> || <code>$0E09</code>: 3593 bytes
|-
| SA-1 || <code>$40C000–$40C47E</code> || <code>$047F</code>: 1151 bytes || <code>$418AFF–$419907</code> || <code>$0E09</code>: 3593 bytes
|}

Los dos bloques internos suman '''4874 bytes en LoROM''' y '''4744 bytes en SA-1'''. La diferencia se debe a los 130 bytes del sistema de dibujo que solo se reservan en LoROM. No se ocupa automáticamente el espacio que queda entre los bloques.

Al deshabilitar una funcionalidad se eliminan sus reservas condicionales y cambian las direcciones posteriores. Aumentar <code>!VRAMTransferSize</code> o <code>!CGRAMTransferSize</code> también aumenta el tamaño de sus tablas.

==== Tablas utilizadas por los sprites ====

<code>DX_FreeRams</code> y <code>DX_FreeRams2</code> '''no son espacios disponibles para escribir variables propias''': a partir de esas posiciones se ubican las tablas de sprites de <code>DynamicXSpritesTables.asm</code> y <code>MoreSpriteMiscs.asm</code>. También debes reservarlas si utilizas esos recursos.

Con la misma configuración de la tabla anterior, sus rangos son:

{| class="wikitable"
! Configuración !! Tablas desde <code>DX_FreeRams</code> !! Tamaño !! Tablas desde <code>DX_FreeRams2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2501–$7E26EC</code> || 492 bytes || <code>$7E3609–$7E3824</code> || 540 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB941–$7FBB2C</code> || 492 bytes || <code>$7FAC82–$7FAE9D</code> || 540 bytes
|-
| SA-1 || <code>$40C47F–$40C6D8</code> || 602 bytes || <code>$419908–$419BCD</code> || 710 bytes
|}

Incluyendo estas tablas, el espacio descrito suma '''5906 bytes en LoROM''' y '''6056 bytes en SA-1'''. Las tablas se calculan para 12 sprites normales en LoROM y 22 en SA-1, además de los slots de cluster, extended y smoke correspondientes.

Normalmente, <code>DX_FreeRams2</code> comienza justo después del segundo bloque interno. En LoROM sin <code>Free7E2000</code> se coloca por separado mediante <code>!Variables3 = $7FAC82</code>; por eso sus tablas no empiezan inmediatamente después de <code>!Variables2</code>.

Dynamic Xtreme también utiliza los espejos existentes del color fijo y de la paleta: <code>$7E0701</code> (2 bytes) y <code>$7E0703</code> (512 bytes) en LoROM. En SA-1 sus direcciones declaradas son <code>$406701</code> y <code>$006703</code>. No son reservas adicionales dentro de los bloques anteriores ni direcciones libres para tus códigos.

==== Reubicar la RAM si hay un conflicto ====

'''Advertencia:''' para reubicar estas variables debes saber qué dirección elegir y considerar el tamaño completo del espacio de memoria que utiliza el sistema. No basta con que una dirección esté libre: debe haber espacio suficiente y las rutinas deben poder acceder a él. Si no tienes conocimientos sobre esto, consulta con alguien que los tenga antes de modificar las direcciones.

Si otro recurso utiliza alguno de estos espacios, puedes modificar '''<code>ASM/DXDefines.asm</code>''' para hacer que Dynamic Xtreme utilice otras zonas disponibles de tu romhack.

* Cambia <code>!Variables</code> y <code>!Variables2</code> en la configuración correspondiente a tu ROM: LoROM con <code>Free7E2000</code>, LoROM sin esa opción o SA-1.
* En LoROM sin <code>Free7E2000</code>, revisa también <code>!Variables3</code>, que determina dónde empiezan las tablas de <code>DX_FreeRams2</code>.
* Reserva espacio suficiente para el bloque completo y las tablas de sprites que le siguen. No basta con que la primera dirección esté libre.
* Respeta el mapa de memoria y los bancos que necesitan las rutinas. No cualquier dirección libre sirve para cualquier acceso.
* Después de cambiar las direcciones, reinstala Dynamic Xtreme y vuelve a insertar PIXI, UberASM y los demás recursos que utilicen sus defines.

Con <code>Free7E2000</code>, Dynamic Xtreme aprovecha el área de RAM que recupera al reubicar los gráficos originales; no la compartas con otros recursos sin comprobar qué parte utiliza. Sin esa opción, las direcciones alternativas pueden coincidir con las de otros recursos habituales. SA-1 utiliza sus propias direcciones y desactiva <code>Free7E2000</code>.

Modifica el archivo de la carpeta '''ASM''', no las copias generadas en <code>ExtraDefines</code> o <code>Patch/ExtraDefines</code>: esas copias se regeneran durante la instalación.

== Recursos hechos con Dynamic Xtreme ==

La mayoría de los recursos desarrollados para Dynamic Xtreme no suelen publicarse en sitios tradicionales como SMW Central debido a que muchos de ellos dependen directamente del framework y sus sistemas avanzados.

En su lugar, los recursos, ejemplos, sistemas y proyectos relacionados con Dynamic Xtreme se encuentran recopilados principalmente en:

https://snestorage.dev

Allí es posible encontrar sprites, sistemas de jugador, efectos gráficos, ejemplos técnicos y otros recursos diseñados específicamente para trabajar con Dynamic Xtreme.

== Conclusión ==

Dynamic Xtreme es un proyecto orientado a modernizar y simplificar el uso de sistemas dinámicos en Super Mario World, ofreciendo herramientas más flexibles, potentes y fáciles de utilizar sin perder compatibilidad ni control avanzado.

El proyecto continúa evolucionando constantemente con nuevas optimizaciones, formatos y herramientas orientadas tanto a usuarios avanzados como a personas que recién comienzan a trabajar con gráficos dinámicos en SNES.

La intención principal de Dynamic Xtreme es permitir la creación de recursos y sistemas cada vez más complejos, manteniendo al mismo tiempo un workflow más limpio, mantenible y accesible para la comunidad.

es/Dynamic Xtreme internal workings

2026-10-25T06:44:33Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_internal_workings}}

En este artículo se explica cómo funciona Dynamic Xtreme, desde la preparación de los recursos al instalarlo hasta la carga y el dibujo de una pose durante el juego.

== Qué prepara la instalación ==

Antes de que un sprite pueda usar sus gráficos o una paleta, Dynamic Xtreme tiene que guardarlos en la ROM y preparar la información para encontrarlos. Lo mismo ocurre con cualquier otro recurso dinámico que hayas añadido.

Para hacerlo, la herramienta lee los DynamicInfo, DrawInfo y PaletteEffect. Cada archivo aporta una parte distinta: qué recursos se van a cargar, cómo se dibujan las poses y qué cambios de color se pueden aplicar.

Gracias a esta preparación se generan defines en <code>DXDefines.asm</code> que permiten utilizar los recursos y ejecutar fácilmente las rutinas necesarias.

=== DynamicInfo: recursos y datos de carga ===

Un DynamicInfo reúne los gráficos de poses, las paletas y los recursos generales que necesita un sprite u otro código. Si incluye gráficos de poses dinámicas, la herramienta los organiza para que puedan cargarse con la distribución de tiles que espera el sistema.

Por cada pose guarda varios datos en tablas separadas. Todas mantienen el mismo orden: la entrada de una pose en una tabla corresponde a esa misma pose en las demás. En la tabla siguiente, '''N''' es la cantidad de poses dinámicas instaladas.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>PoseSize</code> || 2 × N || 2 || La cantidad de datos que utiliza cada pose, en bytes. Se utiliza para comprobar si su carga cabe en el presupuesto del frame.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Cuántos bloques de 16×16 hay que reservar en VRAM para la pose. No siempre coincide exactamente con los bytes que se copian, porque una pieza incompleta también puede necesitar un bloque de espacio.
|-
| <code>PoseResource</code> || 3 × N || 3 || La dirección de los gráficos de cada pose en ROM. Incluye el banco, de modo que el código de carga pueda encontrar su origen completo.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; dos valores por pose || Dos tamaños por pose, correspondientes a los dos tramos en que pueden dividirse sus gráficos. La rutina de carga utiliza esos tamaños para repartirlos correctamente en VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || El desplazamiento en VRAM desde el comienzo del primer tramo hasta el comienzo del segundo. Permite colocar el segundo tramo donde corresponde, aunque el primero termine con una fila incompleta.
|}

Estas tablas describen todas las poses instaladas, no solo las que están en pantalla. Más adelante, la caché guarda por separado cuáles están cargadas y dónde quedaron.

Por ejemplo, si se solicita una pose que todavía no está en VRAM, el sistema consulta cuántos bytes necesita cargar, busca espacio para sus bloques y utiliza la dirección y los datos de sus tramos para preparar la carga.

==== Tablas de paletas ====

Las paletas declaradas en los DynamicInfo se reúnen en <code>PaletteTable</code>. Si '''P''' es la cantidad de entradas de las listas de paletas de los DynamicInfo:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID de cada paleta.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || Dirección de sus colores en ROM.
|}

P cuenta las entradas de las listas, no solo las paletas distintas: una paleta compartida puede aparecer en más de un DynamicInfo.

Las dos listas siguen el orden de las paletas de los DynamicInfo. El define de offset de cada DynamicInfo indica dónde comienza su lista dentro de ellas. Al elegir una versión, el sistema suma ese índice al offset y obtiene tanto el ID como la dirección de los colores elegidos.

El ID permite reconocer y compartir una paleta; la dirección permite cargarla. No son el número de paleta de pantalla: una misma paleta instalada puede terminar, por ejemplo, en la paleta 9 o en la C según la asignación.

==== Recursos generales y defines ====

Los archivos declarados en <code>Resources</code> se guardan en ROM. Su dirección y la cantidad de bytes que ocupan pueden consultarse mediante los defines generados en <code>DXDefines.asm</code>. Por ejemplo, para <code>my_resource.bin</code> se generan:

* <code>!ResourceMyResource</code>: dirección del recurso en ROM.
* <code>!ResourceMyResourceSize</code>: cantidad de bytes que ocupa.
* <code>!ResourceIDMyResource</code>: ID del recurso.

El nombre se normaliza en PascalCase: se eliminan espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra.

=== DrawInfo: datos y rutinas de dibujo ===

El DrawInfo describe cómo está formada una pose: qué tiles tiene, dónde se coloca cada uno, qué tamaño utiliza y cómo cambia al voltearse.

Al instalarlo, Dynamic Xtreme genera rutinas de dibujo optimizadas según los parámetros que utilizan los tiles. Tiene en cuenta, por ejemplo, si necesitan desplazamientos X e Y, si comparten el mismo tamaño, si utilizan propiedades comunes y si requieren volteos.

De esta forma, la rutina realiza el trabajo que necesita ese dibujo sin añadir el manejo de opciones que no utiliza. Varias poses pueden compartirla si necesitan el mismo tratamiento; eso no significa que compartan también sus gráficos o su ID.

La relación entre una pose y su dibujo se guarda en estas tablas. '''D''' es la cantidad de poses de dibujo y '''R''' la cantidad de rutinas generadas:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>TableOffset</code> || 2 × D || 2 || Dónde comienzan los datos de la pose dentro de las tablas de su rutina de dibujo. Así se localizan sus tiles y desplazamientos sin recorrer las poses anteriores.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || La cantidad de tiles de la pose menos uno. Una pose de cuatro tiles guarda 3; la rutina utiliza ese valor para recorrer sus piezas.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Qué rutina de dibujo utiliza cada pose. Las poses con características compatibles pueden apuntar al mismo ID de rutina.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 por rutina || Las direcciones de las rutinas de dibujo. El ID de rutina permite encontrar aquí el código que debe ejecutarse.
|}

Cada rutina tiene, además, las tablas que necesitan sus poses. Aquí '''T''' es la cantidad de entradas de cada tabla de la rutina:

{| class="wikitable"
! Datos !! Bytes totales !! Bytes por valor !! Qué describen
|-
| <code>Tiles</code> || T, si se genera || 1 || Los números de tile que forman la pose.
|-
| <code>Properties</code> || T, si se genera || 1 || Las propiedades de cada pieza, como los volteos y su prioridad respecto a las capas.
|-
| <code>XDisplacements</code> y <code>YDisplacements</code> || T por tabla, si se genera || 1 || La posición de cada tile respecto al punto de origen de la pose.
|-
| Tablas de desplazamientos para los volteos || T por tabla, si se genera || 1 || Las posiciones que deben utilizarse al voltear la pose cuando necesita una distribución distinta.
|-
| <code>Sizes</code> || T, si se genera || 1 || El tamaño de cada tile: 8×8 o 16×16.
|}

No todas estas tablas tienen que aparecer en todas las rutinas. Si un dato es igual para todas las piezas o puede obtenerse de un valor común, la herramienta puede generar una rutina que lo utilice directamente.

La optimización se hace durante la instalación. Si todos los tiles tienen el mismo tamaño, por ejemplo, la rutina puede utilizar ese valor común sin leer un tamaño distinto para cada pieza.

=== PaletteEffect: datos de los efectos ===

Un archivo PaletteEffect contiene una lista de cambios de color. La instalación les asigna IDs y guarda sus datos en <code>PaletteEffectsTable</code>.

Como en las tablas de poses, los datos de cada efecto mantienen la misma posición en las distintas listas. Los IDs de efectos comienzan en 1; el ID 0 se utiliza para indicar que no hay efecto global. En la tabla, '''E''' es la cantidad de efectos instalados; el conjunto ocupa '''2 + 7 × E bytes'''.

{| class="wikitable"
! Parte de la tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>Length</code> || 2 || 2 || La cantidad de efectos instalados.
|-
| <code>Types</code> || E || 1 || El tipo de cada efecto, por ejemplo <code>MixH</code>, <code>MixS</code> o <code>PalTransitionRGB</code>. Indica qué cálculo debe realizarse.
|-
| <code>Value1</code>, <code>Value2</code> y <code>Value3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Los valores de los canales que utiliza el efecto. En una transición, estos tres bytes guardan la dirección de la paleta de destino, no valores de canales.
|-
| <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Cuánto se aplica el cambio en cada componente. Van de 0 a 127.
|}

Si el efecto es una transición hacia otra paleta, la herramienta también prepara esa paleta. Convierte sus colores al formato RGB o HSL que necesita la transición y los guarda en ROM. Durante el juego se puede utilizar ese destino sin tener que convertirlo de nuevo en cada llamada.

Estas paletas de transición son distintas de las paletas normales que se cargan a CGRAM: contienen tres componentes por color y se utilizan para calcular el efecto.

=== Cómo encuentra el código los recursos instalados ===

<code>DXDefines.asm</code> publica los IDs, direcciones, tamaños y offsets que necesitan los recursos. Por ejemplo, <code>!DynamicPoseIDMySpriteIdle</code> identifica una pose y <code>!PaletteEffectIDMyEffect0</code> identifica el primer efecto de un archivo.

Los nombres se normalizan en PascalCase: se eliminan separadores como espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra. <code>my_sprite</code>, por ejemplo, pasa a <code>MySprite</code>.

También se genera <code>BufferTable</code>, que guarda las direcciones de los bloques donde se insertaron los recursos. Cada dirección ocupa 3 bytes y se añade un valor final <code>$FFFFFF</code> de otros 3 bytes. Para B bloques, ocupa <code>3 × (B + 1)</code> bytes. La herramienta utiliza esa información para localizar los datos de una instalación anterior al reinstalar.

Una reinstalación puede cambiar IDs y direcciones. Por eso hay que volver a insertar los sprites, bloques y códigos UberASM que utilizan los defines generados.

== El trabajo de cada frame ==

En la lógica principal se ejecutan el jugador, los sprites y los demás códigos del modo de juego. Los que utilizan Dynamic Xtreme solicitan las poses y paletas que necesitan, preparan los efectos locales y llaman a las rutinas de dibujo. Las cargas que se aceptan quedan anotadas para transferir sus datos durante NMI.

Al terminar esa lógica, el código de game mode de Dynamic Xtreme realiza las tareas que correspondan a las opciones habilitadas: prepara las actualizaciones de VRAM de la optimización de Kevin, mantiene el estado de las paletas y calcula los efectos globales pendientes.

Después, durante NMI, se ejecutan las transferencias preparadas: los gráficos se copian a VRAM y los colores a CGRAM. También se reinicia el contador de datos y se actualizan los relojes del sistema para el siguiente ciclo de trabajo.

El orden que seguiremos para explicarlo es, por tanto, '''lógica principal → tareas al terminar el game mode → transferencias durante NMI'''.

=== Lógica principal ===

Cada recurso decide qué necesita. Un sprite puede cambiar de pose, una animación puede pedir nuevos gráficos y un código UberASM puede cargar una paleta o seleccionar un efecto.

Si la pose solicitada ya está cargada, Dynamic Xtreme actualiza su tiempo de último uso para protegerla del reemplazo y no vuelve a cargar sus gráficos. Si no está cargada, comprueba el presupuesto de datos del frame y busca espacio disponible en VRAM antes de preparar su carga.

El dibujo también se prepara en esta parte: las rutinas escriben en los buffers OAM la posición, los tiles y las propiedades de las piezas que se mostrarán.

Una solicitud puede rechazarse, por ejemplo si no queda presupuesto para sus datos. El recurso que la pidió debe comprobar el resultado y decidir si conserva lo anterior o vuelve a intentarlo después. Una carga rechazada no queda guardada automáticamente para otro frame.

=== Tareas de game mode ===

En esta parte se realizan las siguientes tareas, según las funcionalidades habilitadas.

'''Antes de ejecutar la lógica del juego:'''

# Si está habilitado <code>ControllerOptimization</code>, se ejecuta la rutina del control aquí en lugar de hacerlo en NMI.
# Se comprueba si Dynamic Xtreme debe funcionar en el game mode actual. Si no debe hacerlo, se reinician sus variables. Esto ocurre cada frame que se permanezca en un modo no permitido.

Después se ejecuta la lógica normal del juego, incluidos los sprites y los códigos que solicitan cargas o cambios de paleta.

'''Cuando termina esa lógica:'''

# Si está habilitada la optimización de VRAM de Kevin, se ajustan los destinos de las actualizaciones de Lunar Magic antes de que se transfieran.
# Se ponen en 0 los indicadores de actualización de las paletas y se resta 1 a sus temporizadores de protección si todavía son mayores que 0. Esta parte se omite durante la pausa y en los modos no permitidos.
# Se aplican los efectos globales a las paletas que necesitan actualizarse y se preparan las transferencias de sus colores. Esta parte también se omite si la comprobación anterior impide continuar.

Las copias a VRAM y CGRAM se realizan después, durante NMI. Aquí se deja preparado lo que se va a copiar.

=== Transferencias durante NMI ===

NMI es una interrupción que SNES puede generar al comenzar VBlank, después de dibujar la parte visible de la pantalla. El juego aprovecha ese intervalo para actualizar gráficos, colores y otros datos de video.

En los modos permitidos, la rutina de Dynamic Xtreme reinicia <code>DX_Dynamic_CurrentDataSend</code> y actualiza sus relojes. Después ejecuta las transferencias de gráficos pendientes y luego las de paletas. Si corresponde, también actualiza el color 0,0 preparado por el sistema de efectos.

Para realizar las copias se utiliza DMA. NMI lee cada carga de las listas, configura desde dónde se copiarán los datos, cuántos bytes se copiarán y dónde se colocarán, y ejecuta la transferencia.

El tiempo de VBlank es limitado y SMW también lo necesita para sus actualizaciones de pantalla. Para limitar la cantidad de datos enviados en un frame y evitar flickering, Dynamic Xtreme utiliza <code>DX_Dynamic_CurrentDataSend</code>, que cuenta los bytes de las cargas solicitadas, y <code>DX_Dynamic_MaxDataPerFrame</code>, que establece el límite permitido. Antes de aceptar una carga normal, se comprueba que sus bytes no hagan superar ese límite.

==== Las listas de transferencias ====

Cada transferencia guarda el origen de los datos, su banco, la cantidad de bytes y el destino en VRAM o CGRAM.

Al realizar las copias, NMI recorre las listas desde la última entrada hacia la primera y después las vacía. Esto no borra los gráficos o colores cargados: permanecen en su destino hasta que otro código los cambie.

La lista de VRAM utiliza 0 cuando no tiene entradas. La de CGRAM utiliza <code>$FF</code>, porque guarda el índice de la última entrada en lugar de guardar directamente su cantidad.

Si dos códigos escriben sobre el mismo destino, deben coordinar sus cargas. El orden de las solicitudes no debe utilizarse como sustituto de decidir qué recurso puede ocupar cada espacio.

Normalmente, el recurso se lee desde ROM. Si el recurso se encuentra en un buffer en RAM, el usuario debe conservar su contenido hasta que NMI realice la transferencia. Por ejemplo, si prepara una paleta en RAM, no debe modificar ni reutilizar ese buffer antes de que se copie. La lista guarda su dirección, no una copia de sus datos; Dynamic Xtreme no protege el buffer contra cambios realizados por otros códigos.

==== Presupuesto de datos ====

Las macros de transferencia, como <code>%TransferToVRAM()</code> y <code>%TransferToCGRAM()</code>, comprueban cuántos bytes se han solicitado mediante <code>DX_Dynamic_CurrentDataSend</code>. Si al añadir la nueva carga se supera <code>DX_Dynamic_MaxDataPerFrame</code>, la rechazan. Si la aceptan, suman sus bytes al contador.

El límite predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Su objetivo es evitar flickering por enviar demasiados datos en un mismo frame. Es un límite de cantidad de datos, no una medida exacta del tiempo que tarda cada transferencia.

Estas macros tienen variantes como <code>%ForcedTransferToVRAM()</code> y <code>%ForcedTransferToCGRAM()</code>, que aceptan la carga sin comprobar si supera el límite. Sus bytes también se suman a <code>DX_Dynamic_CurrentDataSend</code>, por lo que reducen lo que queda disponible para las siguientes cargas normales. Se utilizan para cargas prioritarias, como las del jugador; usarlas no evita el flickering si se solicita una cantidad excesiva de datos.

==== Los dos relojes ====

'''DX_Timer: protección de las solicitudes'''

<code>DX_Timer</code> avanza cuando se ejecuta la parte de NMI de Dynamic Xtreme. Además de medir cuánto lleva una pose sin utilizarse, sirve para evitar que un recurso repita sus solicitudes antes de que se procesen las anteriores.

No siempre hay un ciclo de lógica por cada ejecución completa de NMI. Durante slowdown, SMW puede ejecutar una versión reducida de NMI, y puede haber dos ciclos de lógica sin que entre ellos se hayan procesado las listas de transferencias de Dynamic Xtreme.

Sin una protección, un recurso podría añadir otra vez sus cargas a esas listas. Las solicitudes repetidas ocuparían más espacio y podrían provocar flickering.

Para evitarlo, las rutinas con esta protección comparan <code>DX_Timer</code> con un valor guardado por el recurso, normalmente llamado <code>SafeFrame</code>. Si coinciden, el recurso ya hizo su intento con ese valor del reloj y no debe añadir de nuevo las cargas. Si son distintos, guarda el valor actual y puede realizar la nueva solicitud.

<code>DX_Timer</code> continúa avanzando durante la pausa cuando se ejecuta esa parte de NMI.

'''DX_SyncTimer: animaciones sincronizadas'''

La función principal de <code>DX_SyncTimer</code> es dar a los sprites un reloj común para sus animaciones. Por ejemplo, varios sprites que utilizan las mismas poses pueden calcular con este reloj qué pose les corresponde cada cuatro frames.

Así todos cambian al mismo tiempo y solicitan la misma pose. La primera solicitud puede necesitar cargarla; las demás la reutilizan sin programar otra carga de sus gráficos. Esto ahorra transferencias DMA y datos enviados por frame.

Si cada sprite llevara un reloj independiente, podrían terminar usando poses distintas de la misma animación al mismo tiempo y necesitar más cargas y espacio de VRAM.

<code>DX_SyncTimer</code> se detiene durante la pausa y cuando se congela la acción, para que las animaciones sincronizadas también se detengan.

== Carga de gráficos: GraphicsChange ==

<code>GraphicsChange</code> guarda en RAM una lista de solicitudes de carga. Durante NMI se recorren esas solicitudes y se copian sus datos a VRAM.

=== Variables de la lista ===

En esta tabla, '''V''' es el valor de <code>!VRAMTransferSize</code>: 64 por defecto. Las cuatro tablas de solicitudes reservan V bytes cada una; con entradas de 2 bytes, ese valor deja espacio para 32 solicitudes. Junto con el contador, reservan <code>1 + 4 × V</code> bytes: 257 por defecto.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Cantidad de solicitudes pendientes. El valor 0 indica que la lista está vacía.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 por defecto || 2 || Dirección de origen de cada solicitud, sin el banco.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 por defecto || 2 reservados; banco de 1 byte || Banco del origen.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 por defecto || 2 || Cantidad de bytes que se copiarán.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 por defecto || 2 || Dirección de destino en VRAM.
|}

Las tablas mantienen el mismo orden: la primera entrada de cada tabla pertenece a la primera solicitud, la segunda a la segunda, etc. Cada entrada de estas tablas ocupa 2 bytes, por lo que se avanza con desplazamientos de <code>$00</code>, <code>$02</code>, <code>$04</code>, etc.

Estos nombres representan direcciones de RAM calculadas en <code>DXDefines.asm</code>. Sus direcciones pueden cambiar según la configuración y las funcionalidades habilitadas.

=== Añadir una solicitud ===

La macro <code>%TransferToVRAM()</code> realiza los siguientes pasos:

# Calcula cuántos bytes habría en total al añadir la nueva carga a <code>DX_Dynamic_CurrentDataSend</code>.
# Compara el resultado con <code>DX_Dynamic_MaxDataPerFrame</code>. Si lo supera, devuelve el carry desactivado y no añade la solicitud.
# Utiliza <code>DX_PPU_VRAM_Transfer_Length</code> para encontrar la siguiente entrada y aumenta ese contador en 1.
# Guarda el origen, banco, cantidad de bytes y destino en las tablas.
# Actualiza <code>DX_Dynamic_CurrentDataSend</code> con los bytes de la carga y devuelve el carry activado.

<code>%ForcedTransferToVRAM()</code> guarda los mismos datos, pero no comprueba el límite de bytes. Las variantes <code>FromAddr</code> y <code>Resource</code> facilitan obtener el origen desde una dirección completa o desde los defines de un recurso.

Añadir una solicitud no copia los gráficos inmediatamente: deja la información preparada para NMI.

=== Ejecutar las solicitudes durante NMI ===

La rutina <code>VRAMDMA</code>:

# Lee <code>DX_PPU_VRAM_Transfer_Length</code>. Si es 0, termina porque no hay solicitudes.
# Calcula el desplazamiento de la última entrada: <code>(Length - 1) × 2</code>.
# Lee su origen, banco y cantidad de bytes, y los coloca en los registros de DMA.
# Escribe el destino de VRAM en <code>$2116-$2117</code> e inicia la transferencia mediante <code>$420B</code>.
# Retrocede 2 bytes para procesar la solicitud anterior. Repite hasta completar la primera.
# Escribe 0 en <code>DX_PPU_VRAM_Transfer_Length</code> para indicar que la lista está vacía.

'''La lista se ejecuta del final al inicio.''' No hace falta borrar todos sus datos al terminar: al quedar su largo en 0, la próxima solicitud volverá a utilizar la primera entrada.

=== Animaciones con un destino fijo ===

El código de una animación debe:

# Elegir la imagen que corresponde al paso actual.
# Calcular su dirección de origen.
# Solicitar la copia al destino de VRAM de la animación.
# Comprobar el carry. Si se rechaza la carga, conservar la imagen anterior y volver a intentarlo.

El destino puede ser siempre el mismo. Lo que cambia es la imagen que se copia allí; la lista de transferencias no decide cuándo debe avanzar la animación.

Puedes ver un código completo en [[es/Dynamic_Xtreme_UberASM_guide#Crear_animaciones_de_gráficos|Crear animaciones de gráficos de la guía de UberASM]].

=== Carga de una pose dinámica ===

La carga de una pose utiliza la caché para no repetir transferencias de gráficos que ya están disponibles:

# Busca el ID en la tabla hash.
# Si ya está registrado, actualiza su tiempo de uso y no añade otra carga.
# Si no está, comprueba la cantidad de bytes y busca un espacio adecuado en el mapa de VRAM.
# Elige qué poses pueden reemplazarse, teniendo en cuenta su tiempo sin uso y el espacio que necesita la nueva.
# Actualiza las tablas de la caché y el mapa.
# <code>DynamicRoutine</code> divide los datos de la pose en las transferencias necesarias.
# NMI ejecuta esas transferencias.

Cada paso se desarrolla en [[#Sprites_dinámicos:_DynamicPoses|Sprites dinámicos: DynamicPoses]], incluyendo la búsqueda por hash, el mapa, la política de reemplazo y la división de la carga en filas.

== Carga y asignación de paletas: PalettesChange ==

El sistema distingue dos valores:

* '''ID de paleta:''' identifica los colores guardados en ROM.
* '''Color de destino:''' indica desde qué color de la paleta de colores de CGRAM se colocarán los colores que se carguen. Por ejemplo, <code>$91</code> comienza en el color 1 de la paleta 9.

La asignación automática permite compartir colores entre sprites sin exigir un destino fijo para cada uno.

=== Lista de cargas a CGRAM ===

En esta tabla, '''C''' es <code>!CGRAMTransferSize</code>: 64 por defecto. El conjunto reserva <code>1 + 7 × C</code> bytes, es decir, 449 con ese valor. Aunque <code>SourceBNK</code> reserva 2 × C bytes, el código utiliza un byte de banco por solicitud.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Índice de la última solicitud pendiente. <code>$FF</code> indica una lista vacía; 0 indica que hay una solicitud.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 por defecto || 2 || Dirección de origen, sin el banco.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 reservados por defecto || 1 utilizado por solicitud || Banco del origen.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 por defecto || 2 || Cantidad de bytes que se copiarán. Cada color ocupa 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 por defecto || 1 || Primer color de destino en CGRAM.
|}

Durante NMI, <code>CGRAMDMA</code>:

# Comienza por la última solicitud pendiente.
# Configura DMA con el origen y la cantidad de bytes de esa solicitud.
# Selecciona el primer color mediante <code>$2121</code> y realiza la copia.
# Continúa con las solicitudes anteriores.
# Al terminar, escribe <code>$FF</code> en <code>DX_PPU_CGRAM_Transfer_Length</code>.

Las macros <code>TransferPalette</code> también actualizan las copias de colores y el estado de efectos:

* '''Sin efecto global:''' solicitan la carga y actualizan los buffers de SMW. Así el juego no vuelve a utilizar colores anteriores durante la animación de victoria del goal.
* '''Con efecto global:''' guardan los colores originales y preparan el estado necesario para aplicarles el efecto antes de enviarlos a CGRAM.

=== Asignación automática ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || Guarda el ID asignado a cada destino. <code>$FFFF</code> indica una entrada libre y <code>$FFFE</code> una reservada.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protege cada destino del reemplazo automático mientras está en uso.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; un bit por paleta de sprites || Indica qué paletas de sprites están asignadas con efecto global habilitado. Esta condición también se compara al compartir una asignación.
|}

La búsqueda sigue este orden:

# Reutilizar una asignación con el mismo ID y una condición de efecto compatible.
# Si no existe, utilizar una entrada libre.
# Si no hay entradas libres, reemplazar una que no esté reservada y cuyo temporizador sea 0.
# Si no encuentra ninguna, indicar que la asignación falló.

Mientras el recurso utiliza la paleta, mantiene su temporizador en 2. Llegar a 0 no borra los colores: la asignación puede reutilizarse si otro recurso todavía no la reemplazó.

=== Asignación manual y versión ===

* '''Manual con carga:''' el código elige el destino y solicita sus colores.
* '''Manual sin carga:''' el código elige el destino y utiliza los colores que ya estaban preparados.
* '''Versión:''' selecciona una entrada de la lista de paletas del DynamicInfo. La última versión procesada permite comprobar si esa selección cambió.

Dos recursos que elijan el mismo destino con colores distintos deben coordinarse. Mantener la protección de una paleta no significa volver a cargar sus colores.

== Dibujo de poses: DrawingSystem ==

El dibujo prepara las piezas de una pose en OAM: qué tiles se muestran, dónde se colocan y qué propiedades utilizan. Los datos gráficos deben estar en VRAM.

=== Pasos del dibujo ===

# Busca la rutina y los datos de la pose mediante <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code> y <code>TableOffset</code>.
# Obtiene la cantidad de piezas desde <code>NumberOfTilesMinus1</code>.
# Calcula la posición de cada tile usando la posición del sprite, sus desplazamientos y los volteos que correspondan.
# Comprueba si la pieza puede verse y si queda espacio de OAM.
# Escribe su posición, número de tile, propiedades y tamaño en los buffers OAM.

El número de tile depende del dibujo:

{| class="wikitable"
! Caso !! Cómo se obtiene el tile
|-
| Pose dinámica || Se ajusta al lugar de VRAM donde quedaron cargados sus gráficos.
|-
| Pose estática || Se utiliza su número de tile fijo.
|-
| Pose que utiliza un tile común || El código debe preparar <code>!Tile</code> antes de llamar al dibujo.
|}

=== Prioridad y espacio disponible ===

* En '''LoROM''', el sistema lleva su propio control de entradas OAM disponibles.
* En '''SA-1''', utiliza la integración con MaxTile.
* La '''prioridad de dibujo''' organiza las piezas de sprites. No es la misma propiedad que determina si un tile queda delante o detrás de las capas.
* Los '''límites por línea de pantalla''' de SNES siguen existiendo. Tener una pose cargada no garantiza que puedan verse todas sus piezas.

== Jugador y Yoshi ==

=== PlayerFeatures ===

El jugador original tiene rutinas propias para elegir y cargar las piezas de sus poses. <code>PlayerFeatures</code> permite integrar ese trabajo con las cargas de Dynamic Xtreme y cambiar el origen de sus gráficos y paletas.

Con el formato original, el juego sigue eligiendo las piezas de la pose. La rutina obtiene sus direcciones desde el origen configurado y compara esas direcciones con las anteriores para cargar las que hayan cambiado.

Estas cargas utilizan transferencias forzadas y sus bytes también cuentan para las solicitudes normales posteriores. Así conservan su prioridad sin quedar fuera de la contabilidad del sistema.

La paleta del jugador tiene un tratamiento especial: combina colores y selecciones del propio juego con el origen personalizado. No funciona simplemente como sustituir una paleta completa de un sprite cualquiera.

El soporte para jugadores personalizados permite que otros sistemas administren de otra forma sus poses y dibujo. No convierte automáticamente cualquier spritesheet al formato del jugador original.

=== YoshiFeatures ===

Yoshi también carga sus gráficos por piezas. <code>YoshiFeatures</code> permite cambiar su origen manteniendo la organización que esperan sus rutinas.

El código calcula qué partes necesita y prepara sus cargas a los destinos correspondientes de VRAM. Como las del jugador, estas cargas tienen un tratamiento prioritario.

Esta opción necesita <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad. No permite evitar un conflicto del sistema del jugador habilitando únicamente las funciones de Yoshi.

== Memoria y optimizaciones ==

=== Free7E2000 ===

SMW mantiene en RAM gráficos originales del jugador, Yoshi y ciertas animaciones. En ROMs sin SA-1, esta opción adapta las cargas para leer esos datos desde ROM.

Dynamic Xtreme aprovecha la RAM recuperada para sus variables internas. No es un espacio que quede libre para que cualquier otro código escriba encima.

SA-1 utiliza otras direcciones y desactiva esta opción. Los rangos están en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Espacios de RAM utilizados]].

=== ControllerOptimization ===

Esta opción mueve el procesamiento del control desde NMI a la parte de game mode. El objetivo es dejar más tiempo para las actualizaciones de pantalla, no añadir un frame de retraso ni cambiar los botones que recibe el juego.

=== FixedColorOptimization ===

El color fijo se utiliza en las mezclas de color de la consola. Para actualizarlo, el juego prepara sus componentes y los envía al registro correspondiente.

La optimización reemplaza esa preparación por una secuencia más corta. El color sigue enviándose a la consola, pero necesita menos trabajo durante NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic utiliza listas llamadas stripe images para actualizar partes de los mapas de tiles. Esas listas incluyen tanto los datos como la información sobre sus destinos.

La versión integrada de la optimización de Kevin prepara fuera de NMI parte del ajuste de esos destinos. Así deja menos trabajo de preparación para el momento de la transferencia.

Esta opción sustituye el uso del parche original por separado. Además, no debe desinstalarse después de instalarla; hay que tenerlo en cuenta antes de activarla.

=== StatusBarOptimization ===

La barra de estado original actualiza zonas concretas de VRAM. Esta opción prepara sus transferencias de forma más directa, reduciendo la configuración de DMA que necesita hacer durante NMI.

No añade una barra nueva. Modifica la actualización de la original y, por eso, entra en conflicto con recursos que la reemplazan, modifican o eliminan.

== Sprites dinámicos: DynamicPoses ==

El sistema funciona como una '''caché de poses en VRAM'''. No reserva una copia de los gráficos para cada sprite: guarda la pose y permite que la reutilicen todos los recursos que la necesiten.

* Una pose se carga una sola vez mientras permanezca en la caché.
* Las siguientes solicitudes actualizan su tiempo de último uso, sin añadir otra carga de sus gráficos.
* La pose no se borra cuando un recurso deja de utilizarla. Permanece allí hasta que se necesite su espacio y se elija reemplazarla.
* Si fue reemplazada y vuelve a solicitarse, tendrá que cargarse otra vez.

La elección no depende de cuánto tiempo lleva la pose desde que se cargó, sino de '''cuánto tiempo lleva sin utilizarse''' y de si su espacio sirve para la pose nueva.

=== Tres valores distintos ===

{| class="wikitable"
! Valor !! Qué identifica
|-
| ID de pose || La pose instalada. Tiene 16 bits y permite consultar sus datos en ROM.
|-
| Índice de la tabla hash || La entrada de RAM donde se registró la pose. Va de 0 a 127.
|-
| Bloque de VRAM || ID de una de las 128 posiciones para tiles de 16×16 que caben en el espacio de VRAM de sprites. Se numeran de izquierda a derecha y de arriba abajo, desde 0 hasta 127. Para una pose que ocupa varios bloques, se guarda el ID de su primer bloque.
|}

El índice de la tabla hash y el bloque de VRAM no tienen por qué coincidir. Una entrada de la tabla puede registrar una pose que empieza en cualquier bloque permitido.

=== Tablas de las poses registradas ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Cantidad de poses registradas.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Cantidad de poses registradas para cada hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || ID completo de la pose de cada entrada. <code>$FFFF</code> indica una entrada libre.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Bloque de VRAM donde comienza cada pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || Valor de <code>DX_Timer</code> de su último uso.
|}

Estas tablas ocupan '''769 bytes''' en RAM. Guardan las poses registradas durante el juego; las tablas generadas desde el DynamicInfo describen, en cambio, todas las poses instaladas.

=== Cómo se busca una pose ===

La rutina <code>DynamicPoseHashmap_FindPose</code> utiliza una tabla hash de 128 entradas. El hash permite elegir dónde empezar a buscar:

<pre>
hash = ID de pose AND $007F
</pre>

Dos IDs diferentes pueden tener el mismo hash. Por ejemplo, <code>$0005</code> y <code>$0085</code> producen <code>$05</code>. Por eso el hash no basta para confirmar que la pose está cargada: también se compara el ID completo.

La búsqueda sigue estos pasos:

# Guarda el ID solicitado y calcula su hash.
# Si <code>DX_Dynamic_Pose_Length</code> es 0, no hay poses registradas y la búsqueda termina.
# Consulta <code>DX_Dynamic_Pose_HashSize[hash]</code>. Si es 0, ninguna pose registrada tiene ese hash y también termina.
# Comienza por la entrada cuyo índice coincide con el hash.
# Lee el ID de esa entrada. Si coincide con el solicitado, encontró la pose.
# Si no coincide, continúa con la siguiente entrada de la secuencia de búsqueda.

La secuencia avanza '''15 entradas por intento''' y vuelve al comienzo al superar 127:

<pre>
siguiente índice = (índice actual + 15) AND $7F
</pre>

Con 128 entradas, ese paso permite visitar todas las posiciones antes de repetir una. Para el hash <code>$05</code>, el comienzo de la secuencia es:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

==== El contador de poses de cada hash ====

Cada hash tiene su propio contador en <code>DX_Dynamic_Pose_HashSize</code>. Por ejemplo, si hay dos poses registradas cuyo ID produce el hash <code>$05</code>, la entrada <code>DX_Dynamic_Pose_HashSize+$05</code> contiene 2.

Ese número indica '''cuántas poses con ese hash existen''', no cuántas posiciones hay que recorrer. La búsqueda utiliza una copia temporal del contador:

# Comienza con la cantidad de poses registrada para el hash solicitado.
# Recorre las posiciones de la secuencia hasta encontrar el ID solicitado o haber comprobado esa cantidad de poses con el mismo hash.
# Cada vez que encuentra una pose con ese hash, pero con otro ID, resta 1 al contador temporal.
# Las posiciones libres y las poses de otros hashes no descuentan nada: continúa buscando.
# Si el contador temporal llega a 0 sin encontrar el ID, la pose solicitada no está registrada y la búsqueda termina.

El contador de <code>DX_Dynamic_Pose_HashSize</code> no se modifica durante esta búsqueda. Solo se actualiza al añadir o retirar poses de la caché.

Por ejemplo, se busca <code>$0105</code>, que produce el hash <code>$05</code>, y el contador de ese hash vale 2:

{| class="wikitable"
! Posición visitada !! ID guardado !! Hash del ID !! Poses del hash $05 que faltan por comprobar
|-
| <code>$05</code> || <code>$0005</code> || <code>$05</code> || 1: tiene el mismo hash, pero no es el ID solicitado.
|-
| <code>$14</code> || <code>$0014</code> || <code>$14</code> || 1: es otro hash, así que no se descuenta.
|-
| <code>$23</code> || <code>$0085</code> || <code>$05</code> || 0: ya se comprobaron las dos poses con ese hash. <code>$0105</code> no está registrada.
|}

Lo habitual es que haya una o dos poses por hash. Esto permite resolver la búsqueda con pocas comprobaciones y un coste normalmente cercano a <code>O(1)</code>. No significa que siempre se visiten solo una o dos posiciones: puede haber entradas de otros hashes entre ellas. Con muchas colisiones, el recorrido puede ser más largo.

'''Una entrada libre no termina la búsqueda.''' Puede haber quedado vacía al reemplazar una pose y existir otra del mismo hash más adelante. El contador permite saber cuándo ya se comprobaron todas las poses de ese hash, incluso si hay huecos entre ellas.

==== Cuando encuentra la pose ====

<code>TakeDynamicRequest</code>:

# Obtiene el índice de la entrada encontrada.
# Escribe el valor actual de <code>DX_Timer</code> en <code>DX_Dynamic_Pose_TimeLastUse</code> para esa entrada.
# Devuelve el éxito de la solicitud, sin volver a programar la carga de sus gráficos.

Así todos los recursos que solicitan ese ID utilizan la misma pose y la mantienen protegida. No importa si el recurso es un sprite normal, cluster, extended u otro código que utiliza el sistema.

Esto también evita duplicar una carga dentro del mismo ciclo: cuando la primera solicitud se acepta, la pose ya queda registrada aunque la transferencia física se vaya a realizar durante NMI.

=== Cuando la pose no está registrada ===

<code>TakeDynamicRequest</code> continúa con la preparación de una carga nueva:

# Consulta <code>PoseSize</code> y calcula <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# Si supera <code>DX_Dynamic_MaxDataPerFrame</code>, termina con fallo, sin cambiar las poses existentes.
# Consulta <code>Pose16x16Blocks</code> para saber cuántos bloques necesita.
# Llama a <code>VRAMMap_GetBestSlot</code> para buscar un espacio adecuado.
# Si no existe un espacio utilizable, termina con fallo.
# Retira del mapa y de la tabla hash las poses que ocupen el espacio elegido.
# Busca una entrada libre de la tabla hash y registra la pose nueva.
# Actualiza el mapa de VRAM y el contador de datos del frame.
# Llama a <code>DynamicRoutine</code> para añadir las transferencias.

El presupuesto se comprueba antes de reemplazar poses. Si la nueva carga no cabe en el frame, no se libera espacio para una solicitud que no se puede atender.

==== Añadir y quitar entradas de la tabla hash ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> busca una entrada cuyo ID sea <code>$FFFF</code>, siguiendo la misma secuencia de pasos de 15.
* <code>DynamicPoseHashmap_Add</code> guarda el ID y su tiempo de uso, aumenta <code>DX_Dynamic_Pose_Length</code> y aumenta el contador de su hash.
* <code>DynamicPoseHashmap_Remove</code> escribe <code>$FFFF</code> en el ID retirado y reduce ambos contadores.

Retirar una entrada no borra por sí solo los píxeles de VRAM. Indica que esa pose dejó de estar disponible en la caché; las nuevas transferencias sobrescribirán el espacio elegido.

=== Cómo se representa el mapa de VRAM ===

El mapa representa '''128 posiciones de tiles de 16×16 en la VRAM de sprites''', numeradas de izquierda a derecha y de arriba abajo. Cada bloque es una de esas posiciones, no un tramo de 128 bytes contiguos.

Un tile de 16×16 está formado por cuatro tiles de 8×8 distribuidos en dos filas. El mapa administra las posiciones que ocupa la pose; la distribución de sus datos para cargarlos se resuelve después en <code>DynamicRoutine</code>.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Posición donde comienza la sección. El bit <code>$80</code> indica que está restringida: ese espacio no se utiliza para poses dinámicas.
|-
| <code>DX_Dynamic_Tile_Size</code>, también llamada <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || Si el bit <code>$80</code> está activo, los otros bits guardan la cantidad de posiciones de la sección menos uno. Si está desactivado, guardan el índice hash de la pose que ocupa la sección. Para saber si el espacio está restringido, se consulta <code>Offset</code>.
|}

Estas dos tablas ocupan '''256 bytes'''. Junto con las tablas de poses, el administrador utiliza '''1025 bytes''' de RAM, sin contar las listas de transferencias ni las scratch de trabajo.

=== Secciones del mapa ===

Una sección agrupa posiciones consecutivas del mapa que están restringidas, libres o utilizadas por una pose. Su información se guarda en '''la primera y la última posición'''. Esto permite saltar de una sección a la anterior sin revisar todas sus posiciones intermedias.

Los siguientes ejemplos muestran tres estados posibles para una sección de 6 posiciones, de <code>$20</code> a <code>$25</code>. Son casos alternativos, no tres secciones que ocupen el mismo espacio a la vez.

==== Ejemplo 1: sección restringida ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$A0</code> || <code>$80</code> indica restringida y <code>$20</code> indica dónde comienza.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || La sección tiene 6 posiciones: <code>($85 AND $7F) + 1 = 6</code>.
|}

Aunque el bit alto de <code>Size</code> esté activo, '''no es espacio libre para poses dinámicas''': el bit de restricción en <code>Offset</code> hace que se descarte. No se evalúa como una pose que pueda reemplazarse.

<code>DynamicPoseSpaceConfig</code> utiliza este tipo de sección para excluir las partes de SP1-SP4 que no deben utilizar los sprites dinámicos.

==== Ejemplo 2: sección libre ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || Comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || El bit <code>$80</code> indica el tamaño de una sección libre: <code>$05 + 1 = 6</code> posiciones.
|}

Esta sección sí está disponible. Puede alojar una pose que necesite hasta 6 posiciones; si se coloca una de 4, las otras 2 quedan como otra sección libre.

==== Ejemplo 3: sección utilizada por una pose ====

Supongamos que una pose de 6 bloques está registrada en la entrada hash <code>$07</code> y ocupa las posiciones <code>$20</code> a <code>$25</code>:

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || La sección comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$07</code> || El bit <code>$80</code> está desactivado: <code>$07</code> es el índice hash de la pose, no su cantidad de bloques.
|}

Para conocer la cantidad de posiciones y el tiempo sin uso:

# Se lee el ID de la pose en <code>DX_Dynamic_Pose_ID+$0E</code>. Se utiliza <code>$0E</code> porque cada ID ocupa 2 bytes y <code>$07 × 2 = $0E</code>.
# Con ese ID se consulta <code>Pose16x16Blocks</code>, que en este ejemplo contiene 6.
# Se consulta <code>DX_Dynamic_Pose_TimeLastUse+$0E</code> para calcular cuánto lleva sin utilizarse.

La entrada <code>DX_Dynamic_Pose_Offset+$07</code> guarda <code>$20</code>, relacionando esa pose registrada con su posición en VRAM.

=== Recorrido y búsqueda de espacio ===

<code>VRAMMap_GetBestSlot</code> comienza por la posición de tile de 16×16 <code>$7F</code>. Para recorrer el mapa:

# Lee <code>DX_Dynamic_Tile_Offset</code> de la posición actual.
# Obtiene el comienzo de la sección con <code>Offset AND $7F</code>.
# Evalúa esa sección y los espacios que pueda formar con otras secciones contiguas.
# Pasa a la posición <code>comienzo de la sección - 1</code>, que es la última posición de la sección anterior.
# Repite hasta llegar al comienzo del mapa.

Por ejemplo, si las últimas secciones comienzan en <code>$70</code>, <code>$60</code> y <code>$50</code>:

{| class="wikitable"
! Posición visitada !! Comienzo leído de Offset !! Próxima posición
|-
| <code>$7F</code> || <code>$70</code> || <code>$6F</code>
|-
| <code>$6F</code> || <code>$60</code> || <code>$5F</code>
|-
| <code>$5F</code> || <code>$50</code> || <code>$4F</code>
|}

Así recorre '''secciones completas''', no cada tile intermedio.

==== Qué se evalúa durante el recorrido ====

El espacio candidato puede ser '''una sección o varias secciones contiguas'''. En cada paso se comprueba:

* Si hay una sección restringida, no se utiliza ni se combina a través de ella.
* Si hay una pose protegida por su uso reciente, tampoco puede formar parte del espacio.
* Si el candidato todavía es pequeño, se puede continuar con una sección contigua para completar la cantidad de bloques necesaria.
* Si ya cabe la pose, se compara el candidato con el mejor encontrado: primero por su score de tiempo sin uso y después por el espacio suficiente más pequeño.

No se elige una sección solo por contener la pose con más tiempo sin uso. El '''espacio completo''' debe permitir cargar la pose nueva. La puntuación de varias secciones combinadas depende de la pose utilizada más recientemente dentro de ese espacio.

Durante la búsqueda se conservan estos datos temporales:

{| class="wikitable"
! Datos de trabajo !! Bytes totales !! Bytes por valor !! Para qué se usan
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 por campo || Comienzo, score y cantidad de bloques del espacio candidato actual.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 por campo || Los mismos campos para el mejor espacio encontrado.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Cantidad de bloques que necesita la pose nueva.
|}

Estos nombres utilizan scratch de trabajo, no RAM persistente adicional.

=== Política de reemplazo: tiempo sin uso y espacio suficiente ===

El sistema no elige simplemente la pose que se cargó primero. Utiliza el tiempo transcurrido desde su '''último uso''':

<pre>
tiempo sin uso = DX_Timer - TimeLastUse de la pose
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> obtiene el tamaño y una puntuación para cada región:

{| class="wikitable"
! Caso !! Puntuación y tratamiento
|-
| Región libre || <code>$FF</code>. Se favorece frente a regiones ocupadas.
|-
| Región ocupada || Tiempo sin uso, limitado a <code>$FE</code>.
|-
| Tiempo sin uso de 0 o 1 || No se puede reemplazar: la pose sigue protegida.
|-
| Región restringida || Se descarta: ese espacio no se utiliza para poses dinámicas.
|}

La protección exige '''al menos dos avances de <code>DX_Timer</code> sin utilizar la pose'''. Cada recurso que vuelve a solicitarla actualiza su tiempo de uso y vuelve a protegerla.

==== Por qué no siempre se reemplaza la pose con más tiempo sin uso ====

La pose nueva necesita espacio suficiente y contiguo. Un espacio pequeño no sirve por sí solo, aunque lleve mucho tiempo sin utilizarse.

Por ejemplo, para una pose nueva de 4 bloques:

{| class="wikitable"
! Espacio candidato !! Tiempo sin uso !! ¿Sirve?
|-
| Pose A: 2 bloques, sin espacio contiguo utilizable || 20 || No: solo deja 2 bloques.
|-
| Pose B: 4 bloques || 8 || Sí: puede alojar la pose nueva.
|}

En este caso se puede reemplazar B y conservar A. A lleva más tiempo sin uso, pero su espacio no permite atender la solicitud.

Si dos o más regiones contiguas pueden reemplazarse, el sistema puede considerarlas juntas. Para esa combinación:

* Suma sus cantidades de bloques.
* Utiliza la '''menor puntuación''' de las regiones combinadas, es decir, el menor tiempo sin uso.
* Si una está restringida o protegida, no puede utilizarla para completar el espacio.

Así una pose usada recientemente no puede quedar sobrescrita por combinarla con otra que lleva mucho tiempo sin uso.

==== Elegir entre candidatos válidos ====

# El candidato debe tener al menos la cantidad de bloques solicitada.
# Se prefiere la puntuación más alta: espacio libre o mayor tiempo sin uso.
# Si las puntuaciones son iguales, se prefiere el candidato con menos bloques, siempre que la pose quepa.
# Si puntuación y tamaño también coinciden, se conserva el candidato que ya se había elegido.

Las regiones se combinan durante la búsqueda cuando el candidato todavía es demasiado pequeño. No se juntan todas las regiones reemplazables sin tener en cuenta el tamaño solicitado.

=== Reemplazar y dividir la región elegida ===

Una vez elegido el espacio:

# <code>VRAMMap_RemovePosesInSpace</code> recorre sus regiones y retira de la tabla hash las poses que haya que reemplazar.
# <code>VRAMMap_RemoveSpace</code> representa el espacio elegido como una región libre, actualizando sus extremos.
# Se busca una entrada hash libre y se guarda el bloque de comienzo en <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registra la pose.
# <code>VRAMMap_AddPoseInSpace</code> escribe el índice hash de la pose y el comienzo de su región en el primer y último bloque.
# Si sobran bloques, crea otra región libre con el resto.

Si una región de 6 bloques aloja una pose de 4, quedan una región ocupada de 4 y una libre de 2. No se mueven las demás poses para compactar VRAM.

=== DynamicRoutine: preparar las transferencias de la pose ===

En este punto ya se eligió el espacio y se registró la pose. <code>DynamicRoutine</code> convierte esa asignación en solicitudes de transferencia.

Utiliza estos datos:

{| class="wikitable"
! Dato !! Cantidad consultada por pose !! Para qué sirve
|-
| Bloque de comienzo || 1 byte || Lugar elegido por el mapa de VRAM.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes de una tabla de 256 bytes || Convierte uno de los 128 bloques en un desplazamiento de VRAM.
|-
| <code>PoseResource</code> || 3 bytes || Dirección completa de los datos de la pose en ROM.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: dos valores de 2 || Cantidad de bytes del primer y del segundo tramo.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || Desplazamiento de VRAM para el segundo tramo.
|}

==== Convertir el bloque en una dirección de VRAM ====

Los bloques de 16×16 no se convierten simplemente en un desplazamiento lineal de bytes. Cada uno utiliza tiles de 8×8 distribuidos en las filas de VRAM.

<code>OffsetToVRAMOffset</code> contempla esa distribución. Por ejemplo:

{| class="wikitable"
! Bloque !! Desplazamiento !! Dirección de VRAM
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

Estas direcciones de VRAM están expresadas en palabras de 2 bytes, no en bytes. La rutina suma la base <code>$6000</code> utilizada para los gráficos de sprites.

==== Procesar los tramos y sus filas ====

# Obtiene el origen desde <code>PoseResource</code>.
# Procesa los bytes del primer tramo mediante <code>DynamicRoutineLine</code>.
# Si el segundo tramo tiene tamaño 0, termina.
# Si existe, adelanta el origen la cantidad de bytes del primer tramo.
# Suma <code>PoseSecondLineOffset</code> al desplazamiento de VRAM y procesa el segundo tramo.

<code>DynamicRoutineLine</code> divide cada tramo según las filas y el punto de comienzo. Para un destino V expresado en palabras de VRAM, prepara:

<pre>
Final de la primera fila = (V + $0100) AND $FF00
Bytes hasta ese final = (final de la primera fila - V) × 2
Destino de la segunda parte = final de la primera fila + $0100
Bytes de la segunda parte de un grupo = $0200 - bytes de la primera
</pre>

Los tamaños son cantidades de bytes, mientras que los destinos de VRAM están expresados en palabras. Por eso se multiplica por 2 al calcular cuántos datos caben hasta el final de una fila.

La rutina utiliza tres recorridos:

* <code>.EndLine</code>: añade una solicitud final con los bytes restantes.
* <code>.TwoLinesWithEndLine</code>: añade dos solicitudes para los datos restantes, cada una con su destino y cantidad de bytes.
* <code>.TwoLines</code>: añade dos solicitudes que suman <code>$0200</code> bytes, avanza el origen y los destinos y repite con los datos que faltan.

Hay un caso directo antes del recorrido general: si el destino comienza en un límite de <code>$0100</code> palabras y el tramo tiene al menos <code>$0200</code> bytes, la rutina utiliza <code>.EndLine</code> para preparar la copia del tramo completo en una solicitud.

Por ejemplo, un tramo de <code>$0200</code> bytes que comienza en <code>$6020</code> se divide así:

{| class="wikitable"
! Solicitud !! Origen !! Destino VRAM !! Bytes
|-
| Primera || Comienzo del tramo || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Segunda || Comienzo del tramo + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Las dos solicitudes copian los 512 bytes del tramo, respetando los destinos que calcula la distribución de filas. No son dos copias completas de la pose.

Cada solicitud utiliza estas tablas:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Por cada solicitud añadida aumenta <code>DX_PPU_VRAM_Transfer_Length</code>.

La cantidad total de bytes de la pose ya se comprobó y se añadió a <code>DX_Dynamic_CurrentDataSend</code> en <code>TakeDynamicRequest</code>. Esta parte divide esa carga en transferencias; no vuelve a contar la pose completa por cada solicitud.

<code>DynamicRoutine</code> '''no ejecuta DMA'''. Deja las solicitudes preparadas para que <code>VRAMDMA</code> las copie durante NMI.

=== Qué conserva el sprite ===

Las rutinas de sprites guardan el índice hash de la pose utilizable, no una copia independiente de sus gráficos. Ese índice permite consultar su bloque de VRAM y mantener actualizado su tiempo de uso.

Si una pose nueva no puede cargarse:

* Si existe una pose anterior válida, se mantiene y se actualiza su tiempo de uso para protegerla.
* Si nunca hubo una pose válida, no se debe dibujar como si la solicitud hubiera tenido éxito.
* En las llamadas con soporte para mantener la anterior, el carry puede indicar que todavía hay una pose utilizable aunque no se haya completado el cambio.

La animación y el movimiento siguen siendo responsabilidad del sprite. La caché se ocupa de reutilizar o preparar los gráficos solicitados.

== Efectos de paleta: PalettesEffects ==

El sistema conserva los colores originales para poder cambiar de efecto, combinarlo con otro o volver a la paleta sin efecto. No debe utilizar el resultado ya afectado como si fuera la paleta original.

=== Buffers de colores ===

{| class="wikitable"
! Variable o buffer !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 por color || Colores de base en formato SNES, con 2 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 por color || Base separada en rojo, verde y azul, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 por color || Base separada en tono, saturación y luminosidad, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 por color || Resultado en formato SNES, listo para solicitar su copia a CGRAM. Corresponde al buffer de paletas del juego.
|}

=== Indicadores de cada paleta ===

Cada bit de estos indicadores corresponde a una paleta. Las variables <code>BG</code> cubren 0-7 y las <code>SP</code> cubren 8-F.

{| class="wikitable"
! Variables !! Bytes totales !! Bytes por valor !! Qué indican
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> y <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si ya se preparó la base de colores en formato SNES.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> y <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparado el resultado del efecto global.
|}

Estos indicadores evitan repetir conversiones y cálculos que siguen siendo válidos.

=== Preparar una base ===

# Se comprueba si la paleta ya tiene una base registrada.
# Si no la tiene, se obtienen los colores del buffer del juego. Una carga explícita, como <code>TransferPalette</code>, puede proporcionar esa base directamente.
# Se comprueba si el efecto necesita RGB o HSL.
# Si falta esa conversión, se prepara y se marca como disponible.

Si solo cambia el efecto, la base puede seguir siendo válida. Si cambian los colores originales, las llamadas de carga actualizan la base e invalidan las conversiones y resultados que deben calcularse otra vez.

=== Datos de un efecto ===

El ID permite consultar las tablas generadas durante la instalación:

* <code>Types</code>: cálculo que debe realizarse.
* <code>Value1</code>, <code>Value2</code> y <code>Value3</code>: valores de los canales o dirección de la paleta de destino de una transición.
* <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code>: cuánto se aplica cada cambio.

Los canales utilizan valores de 0 a 31. Los ratios van de 0 a 127: 0 conserva el origen y 127 aplica por completo el cambio elegido.

Los cálculos se realizan fuera de NMI. NMI realiza la transferencia de los colores resultantes.

=== Efecto global ===

{| class="wikitable"
! Variable !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selecciona el efecto global. El valor 0 permite restaurar los colores de base.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 0-7 que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 8-F que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Guarda el último ID global procesado por cada paleta.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controla la participación del color fijo y el color 0,0.
|}

Para cada paleta habilitada, el administrador:

# Comprueba si necesita actualizar el resultado del efecto.
# Prepara la base RGB o HSL si todavía falta.
# Calcula el efecto si el resultado anterior ya no sirve.
# Prepara los colores en formato SNES y solicita su transferencia.
# Confirma el ID procesado cuando la carga correspondiente se acepta.

Si se mantiene el mismo efecto y no cambió la base, no hace falta calcularlo otra vez. Al cambiar el ID global se invalidan los resultados anteriores, no necesariamente las bases RGB y HSL.

El ID global 0 también requiere una actualización: el sistema debe cargar de nuevo los colores de base para quitar el efecto anterior.

=== Efecto local y concatenación ===

Un recurso puede tener un efecto propio y recibir también el global. Por ejemplo, un sprite puede cambiar de tono y después oscurecerse junto con el nivel.

El orden es:

# Preparar el resultado del efecto local.
# Utilizarlo como base para el efecto global mediante la llamada de concatenación.
# Calcular el efecto global sobre esa base.
# Cargar el resultado combinado, sin mostrar antes la versión que solo tiene el efecto local.

* La concatenación RGB se utiliza con efectos RGB.
* La concatenación HSL se utiliza con efectos HSL.
* Los recursos que comparten un destino de CGRAM comparten sus colores. Para mostrar dos efectos locales distintos, necesitan destinos que permitan mantener ambos resultados.

=== Si no se acepta la transferencia ===

* Calcular el efecto no significa que ya esté en CGRAM.
* Si la transferencia no se acepta, el administrador puede volver a intentar la actualización.
* Cuando corresponde, se mantiene el resultado anterior utilizable hasta poder sustituirlo.
* No se deben cargar primero los colores originales sin efecto: podrían verse así durante un frame antes del resultado correcto.

== Cómo trabajan juntos ==

El recorrido de un sprite dinámico reúne estas tareas:

# Su lógica elige la pose y la versión de paleta.
# La asignación busca una paleta utilizable y prepara los colores si hace falta.
# La caché protege la pose ya cargada o prepara la carga de una nueva.
# El dibujo escribe los datos de sus piezas en los buffers OAM.
# El administrador de efectos prepara los cambios globales pendientes.
# NMI realiza las transferencias de gráficos y colores solicitadas.

Compartir gráficos, compartir una paleta y compartir una rutina de dibujo son tres cosas distintas. Dynamic Xtreme puede aprovechar cada una sin obligar a que los recursos compartan también las demás.

== Lecturas relacionadas ==

* [[es/Dynamic_Xtreme|Artículo principal]]: funcionalidades y compatibilidad.
* [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos]].
* [[es/Dynamic_Xtreme_sprite_creation_guide|Creación de sprites dinámicos]].
* [[es/Dynamic_Xtreme_UberASM_guide|Dynamic Xtreme con UberASM]].
* [[es/Dynamic_Xtreme_ASM_API|API ASM]].

es/Dynamic Xtreme internal workings

2026-10-25T03:08:29Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_internal_workings}}

En este artículo se explica cómo funciona Dynamic Xtreme, desde la preparación de los recursos al instalarlo hasta la carga y el dibujo de una pose durante el juego.

== Qué prepara la instalación ==

Antes de que un sprite pueda usar sus gráficos o una paleta, Dynamic Xtreme tiene que guardarlos en la ROM y preparar la información para encontrarlos. Lo mismo ocurre con cualquier otro recurso dinámico que hayas añadido.

Para hacerlo, la herramienta lee los DynamicInfo, DrawInfo y PaletteEffect. Cada archivo aporta una parte distinta: qué recursos se van a cargar, cómo se dibujan las poses y qué cambios de color se pueden aplicar.

Gracias a esta preparación se generan defines en <code>DXDefines.asm</code> que permiten utilizar los recursos y ejecutar fácilmente las rutinas necesarias.

=== DynamicInfo: recursos y datos de carga ===

Un DynamicInfo reúne los gráficos de poses, las paletas y los recursos generales que necesita un sprite u otro código. Si incluye gráficos de poses dinámicas, la herramienta los organiza para que puedan cargarse con la distribución de tiles que espera el sistema.

Por cada pose guarda varios datos en tablas separadas. Todas mantienen el mismo orden: la entrada de una pose en una tabla corresponde a esa misma pose en las demás. En la tabla siguiente, '''N''' es la cantidad de poses dinámicas instaladas.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>PoseSize</code> || 2 × N || 2 || La cantidad de datos que utiliza cada pose, en bytes. Se utiliza para comprobar si su carga cabe en el presupuesto del frame.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Cuántos bloques de 16×16 hay que reservar en VRAM para la pose. No siempre coincide exactamente con los bytes que se copian, porque una pieza incompleta también puede necesitar un bloque de espacio.
|-
| <code>PoseResource</code> || 3 × N || 3 || La dirección de los gráficos de cada pose en ROM. Incluye el banco, de modo que el código de carga pueda encontrar su origen completo.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; dos valores por pose || Dos tamaños por pose, correspondientes a los dos tramos en que pueden dividirse sus gráficos. La rutina de carga utiliza esos tamaños para repartirlos correctamente en VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || El desplazamiento en VRAM desde el comienzo del primer tramo hasta el comienzo del segundo. Permite colocar el segundo tramo donde corresponde, aunque el primero termine con una fila incompleta.
|}

Estas tablas describen todas las poses instaladas, no solo las que están en pantalla. Más adelante, la caché guarda por separado cuáles están cargadas y dónde quedaron.

Por ejemplo, si se solicita una pose que todavía no está en VRAM, el sistema consulta cuántos bytes necesita cargar, busca espacio para sus bloques y utiliza la dirección y los datos de sus tramos para preparar la carga.

==== Tablas de paletas ====

Las paletas declaradas en los DynamicInfo se reúnen en <code>PaletteTable</code>. Si '''P''' es la cantidad de entradas de las listas de paletas de los DynamicInfo:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID de cada paleta.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || Dirección de sus colores en ROM.
|}

P cuenta las entradas de las listas, no solo las paletas distintas: una paleta compartida puede aparecer en más de un DynamicInfo.

Las dos listas siguen el orden de las paletas de los DynamicInfo. El define de offset de cada DynamicInfo indica dónde comienza su lista dentro de ellas. Al elegir una versión, el sistema suma ese índice al offset y obtiene tanto el ID como la dirección de los colores elegidos.

El ID permite reconocer y compartir una paleta; la dirección permite cargarla. No son el número de paleta de pantalla: una misma paleta instalada puede terminar, por ejemplo, en la paleta 9 o en la C según la asignación.

==== Recursos generales y defines ====

Los archivos declarados en <code>Resources</code> se guardan en ROM. Su dirección y la cantidad de bytes que ocupan pueden consultarse mediante los defines generados en <code>DXDefines.asm</code>. Por ejemplo, para <code>my_resource.bin</code> se generan:

* <code>!ResourceMyResource</code>: dirección del recurso en ROM.
* <code>!ResourceMyResourceSize</code>: cantidad de bytes que ocupa.
* <code>!ResourceIDMyResource</code>: ID del recurso.

El nombre se normaliza en PascalCase: se eliminan espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra.

=== DrawInfo: datos y rutinas de dibujo ===

El DrawInfo describe cómo está formada una pose: qué tiles tiene, dónde se coloca cada uno, qué tamaño utiliza y cómo cambia al voltearse.

Al instalarlo, Dynamic Xtreme genera rutinas de dibujo optimizadas según los parámetros que utilizan los tiles. Tiene en cuenta, por ejemplo, si necesitan desplazamientos X e Y, si comparten el mismo tamaño, si utilizan propiedades comunes y si requieren volteos.

De esta forma, la rutina realiza el trabajo que necesita ese dibujo sin añadir el manejo de opciones que no utiliza. Varias poses pueden compartirla si necesitan el mismo tratamiento; eso no significa que compartan también sus gráficos o su ID.

La relación entre una pose y su dibujo se guarda en estas tablas. '''D''' es la cantidad de poses de dibujo y '''R''' la cantidad de rutinas generadas:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>TableOffset</code> || 2 × D || 2 || Dónde comienzan los datos de la pose dentro de las tablas de su rutina de dibujo. Así se localizan sus tiles y desplazamientos sin recorrer las poses anteriores.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || La cantidad de tiles de la pose menos uno. Una pose de cuatro tiles guarda 3; la rutina utiliza ese valor para recorrer sus piezas.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Qué rutina de dibujo utiliza cada pose. Las poses con características compatibles pueden apuntar al mismo ID de rutina.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 por rutina || Las direcciones de las rutinas de dibujo. El ID de rutina permite encontrar aquí el código que debe ejecutarse.
|}

Cada rutina tiene, además, las tablas que necesitan sus poses. Aquí '''T''' es la cantidad de entradas de cada tabla de la rutina:

{| class="wikitable"
! Datos !! Bytes totales !! Bytes por valor !! Qué describen
|-
| <code>Tiles</code> || T, si se genera || 1 || Los números de tile que forman la pose.
|-
| <code>Properties</code> || T, si se genera || 1 || Las propiedades de cada pieza, como los volteos y su prioridad respecto a las capas.
|-
| <code>XDisplacements</code> y <code>YDisplacements</code> || T por tabla, si se genera || 1 || La posición de cada tile respecto al punto de origen de la pose.
|-
| Tablas de desplazamientos para los volteos || T por tabla, si se genera || 1 || Las posiciones que deben utilizarse al voltear la pose cuando necesita una distribución distinta.
|-
| <code>Sizes</code> || T, si se genera || 1 || El tamaño de cada tile: 8×8 o 16×16.
|}

No todas estas tablas tienen que aparecer en todas las rutinas. Si un dato es igual para todas las piezas o puede obtenerse de un valor común, la herramienta puede generar una rutina que lo utilice directamente.

La optimización se hace durante la instalación. Si todos los tiles tienen el mismo tamaño, por ejemplo, la rutina puede utilizar ese valor común sin leer un tamaño distinto para cada pieza.

=== PaletteEffect: datos de los efectos ===

Un archivo PaletteEffect contiene una lista de cambios de color. La instalación les asigna IDs y guarda sus datos en <code>PaletteEffectsTable</code>.

Como en las tablas de poses, los datos de cada efecto mantienen la misma posición en las distintas listas. Los IDs de efectos comienzan en 1; el ID 0 se utiliza para indicar que no hay efecto global. En la tabla, '''E''' es la cantidad de efectos instalados; el conjunto ocupa '''2 + 7 × E bytes'''.

{| class="wikitable"
! Parte de la tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>Length</code> || 2 || 2 || La cantidad de efectos instalados.
|-
| <code>Types</code> || E || 1 || El tipo de cada efecto, por ejemplo <code>MixH</code>, <code>MixS</code> o <code>PalTransitionRGB</code>. Indica qué cálculo debe realizarse.
|-
| <code>Value1</code>, <code>Value2</code> y <code>Value3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Los valores de los canales que utiliza el efecto. En una transición, estos tres bytes guardan la dirección de la paleta de destino, no valores de canales.
|-
| <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Cuánto se aplica el cambio en cada componente. Van de 0 a 127.
|}

Si el efecto es una transición hacia otra paleta, la herramienta también prepara esa paleta. Convierte sus colores al formato RGB o HSL que necesita la transición y los guarda en ROM. Durante el juego se puede utilizar ese destino sin tener que convertirlo de nuevo en cada llamada.

Estas paletas de transición son distintas de las paletas normales que se cargan a CGRAM: contienen tres componentes por color y se utilizan para calcular el efecto.

=== Cómo encuentra el código los recursos instalados ===

<code>DXDefines.asm</code> publica los IDs, direcciones, tamaños y offsets que necesitan los recursos. Por ejemplo, <code>!DynamicPoseIDMySpriteIdle</code> identifica una pose y <code>!PaletteEffectIDMyEffect0</code> identifica el primer efecto de un archivo.

Los nombres se normalizan en PascalCase: se eliminan separadores como espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra. <code>my_sprite</code>, por ejemplo, pasa a <code>MySprite</code>.

También se genera <code>BufferTable</code>, que guarda las direcciones de los bloques donde se insertaron los recursos. Cada dirección ocupa 3 bytes y se añade un valor final <code>$FFFFFF</code> de otros 3 bytes. Para B bloques, ocupa <code>3 × (B + 1)</code> bytes. La herramienta utiliza esa información para localizar los datos de una instalación anterior al reinstalar.

Una reinstalación puede cambiar IDs y direcciones. Por eso hay que volver a insertar los sprites, bloques y códigos UberASM que utilizan los defines generados.

== El trabajo de cada frame ==

En la lógica principal se ejecutan el jugador, los sprites y los demás códigos del modo de juego. Los que utilizan Dynamic Xtreme solicitan las poses y paletas que necesitan, preparan los efectos locales y llaman a las rutinas de dibujo. Las cargas que se aceptan quedan anotadas para transferir sus datos durante NMI.

Al terminar esa lógica, el código de game mode de Dynamic Xtreme realiza las tareas que correspondan a las opciones habilitadas: prepara las actualizaciones de VRAM de la optimización de Kevin, mantiene el estado de las paletas y calcula los efectos globales pendientes.

Después, durante NMI, se ejecutan las transferencias preparadas: los gráficos se copian a VRAM y los colores a CGRAM. También se reinicia el contador de datos y se actualizan los relojes del sistema para el siguiente ciclo de trabajo.

El orden que seguiremos para explicarlo es, por tanto, '''lógica principal → tareas al terminar el game mode → transferencias durante NMI'''.

=== Lógica principal ===

Cada recurso decide qué necesita. Un sprite puede cambiar de pose, una animación puede pedir nuevos gráficos y un código UberASM puede cargar una paleta o seleccionar un efecto.

Si la pose solicitada ya está cargada, Dynamic Xtreme actualiza su tiempo de último uso para protegerla del reemplazo y no vuelve a cargar sus gráficos. Si no está cargada, comprueba el presupuesto de datos del frame y busca espacio disponible en VRAM antes de preparar su carga.

El dibujo también se prepara en esta parte: las rutinas escriben en los buffers OAM la posición, los tiles y las propiedades de las piezas que se mostrarán.

Una solicitud puede rechazarse, por ejemplo si no queda presupuesto para sus datos. El recurso que la pidió debe comprobar el resultado y decidir si conserva lo anterior o vuelve a intentarlo después. Una carga rechazada no queda guardada automáticamente para otro frame.

=== Tareas de game mode ===

En esta parte se realizan las siguientes tareas, según las funcionalidades habilitadas.

'''Antes de ejecutar la lógica del juego:'''

# Si está habilitado <code>ControllerOptimization</code>, se ejecuta la rutina del control aquí en lugar de hacerlo en NMI.
# Se comprueba si Dynamic Xtreme debe funcionar en el game mode actual. Si no debe hacerlo, se reinician sus variables. Esto ocurre cada frame que se permanezca en un modo no permitido.

Después se ejecuta la lógica normal del juego, incluidos los sprites y los códigos que solicitan cargas o cambios de paleta.

'''Cuando termina esa lógica:'''

# Si está habilitada la optimización de VRAM de Kevin, se ajustan los destinos de las actualizaciones de Lunar Magic antes de que se transfieran.
# Se ponen en 0 los indicadores de actualización de las paletas y se resta 1 a sus temporizadores de protección si todavía son mayores que 0. Esta parte se omite durante la pausa y en los modos no permitidos.
# Se aplican los efectos globales a las paletas que necesitan actualizarse y se preparan las transferencias de sus colores. Esta parte también se omite si la comprobación anterior impide continuar.

Las copias a VRAM y CGRAM se realizan después, durante NMI. Aquí se deja preparado lo que se va a copiar.

=== Transferencias durante NMI ===

NMI es una interrupción que SNES puede generar al comenzar VBlank, después de dibujar la parte visible de la pantalla. El juego aprovecha ese intervalo para actualizar gráficos, colores y otros datos de video.

En los modos permitidos, la rutina de Dynamic Xtreme reinicia <code>DX_Dynamic_CurrentDataSend</code> y actualiza sus relojes. Después ejecuta las transferencias de gráficos pendientes y luego las de paletas. Si corresponde, también actualiza el color 0,0 preparado por el sistema de efectos.

Para realizar las copias se utiliza DMA. NMI lee cada carga de las listas, configura desde dónde se copiarán los datos, cuántos bytes se copiarán y dónde se colocarán, y ejecuta la transferencia.

El tiempo de VBlank es limitado y SMW también lo necesita para sus actualizaciones de pantalla. Para limitar la cantidad de datos enviados en un frame y evitar flickering, Dynamic Xtreme utiliza <code>DX_Dynamic_CurrentDataSend</code>, que cuenta los bytes de las cargas solicitadas, y <code>DX_Dynamic_MaxDataPerFrame</code>, que establece el límite permitido. Antes de aceptar una carga normal, se comprueba que sus bytes no hagan superar ese límite.

==== Las listas de transferencias ====

Cada transferencia guarda el origen de los datos, su banco, la cantidad de bytes y el destino en VRAM o CGRAM.

Al realizar las copias, NMI recorre las listas desde la última entrada hacia la primera y después las vacía. Esto no borra los gráficos o colores cargados: permanecen en su destino hasta que otro código los cambie.

La lista de VRAM utiliza 0 cuando no tiene entradas. La de CGRAM utiliza <code>$FF</code>, porque guarda el índice de la última entrada en lugar de guardar directamente su cantidad.

Si dos códigos escriben sobre el mismo destino, deben coordinar sus cargas. El orden de las solicitudes no debe utilizarse como sustituto de decidir qué recurso puede ocupar cada espacio.

Normalmente, el recurso se lee desde ROM. Si el recurso se encuentra en un buffer en RAM, el usuario debe conservar su contenido hasta que NMI realice la transferencia. Por ejemplo, si prepara una paleta en RAM, no debe modificar ni reutilizar ese buffer antes de que se copie. La lista guarda su dirección, no una copia de sus datos; Dynamic Xtreme no protege el buffer contra cambios realizados por otros códigos.

==== Presupuesto de datos ====

Las macros de transferencia, como <code>%TransferToVRAM()</code> y <code>%TransferToCGRAM()</code>, comprueban cuántos bytes se han solicitado mediante <code>DX_Dynamic_CurrentDataSend</code>. Si al añadir la nueva carga se supera <code>DX_Dynamic_MaxDataPerFrame</code>, la rechazan. Si la aceptan, suman sus bytes al contador.

El límite predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Su objetivo es evitar flickering por enviar demasiados datos en un mismo frame. Es un límite de cantidad de datos, no una medida exacta del tiempo que tarda cada transferencia.

Estas macros tienen variantes como <code>%ForcedTransferToVRAM()</code> y <code>%ForcedTransferToCGRAM()</code>, que aceptan la carga sin comprobar si supera el límite. Sus bytes también se suman a <code>DX_Dynamic_CurrentDataSend</code>, por lo que reducen lo que queda disponible para las siguientes cargas normales. Se utilizan para cargas prioritarias, como las del jugador; usarlas no evita el flickering si se solicita una cantidad excesiva de datos.

==== Los dos relojes ====

'''DX_Timer: protección de las solicitudes'''

<code>DX_Timer</code> avanza cuando se ejecuta la parte de NMI de Dynamic Xtreme. Además de medir cuánto lleva una pose sin utilizarse, sirve para evitar que un recurso repita sus solicitudes antes de que se procesen las anteriores.

No siempre hay un ciclo de lógica por cada ejecución completa de NMI. Durante slowdown, SMW puede ejecutar una versión reducida de NMI, y puede haber dos ciclos de lógica sin que entre ellos se hayan procesado las listas de transferencias de Dynamic Xtreme.

Sin una protección, un recurso podría añadir otra vez sus cargas a esas listas. Las solicitudes repetidas ocuparían más espacio y podrían provocar flickering.

Para evitarlo, las rutinas con esta protección comparan <code>DX_Timer</code> con un valor guardado por el recurso, normalmente llamado <code>SafeFrame</code>. Si coinciden, el recurso ya hizo su intento con ese valor del reloj y no debe añadir de nuevo las cargas. Si son distintos, guarda el valor actual y puede realizar la nueva solicitud.

<code>DX_Timer</code> continúa avanzando durante la pausa cuando se ejecuta esa parte de NMI.

'''DX_SyncTimer: animaciones sincronizadas'''

La función principal de <code>DX_SyncTimer</code> es dar a los sprites un reloj común para sus animaciones. Por ejemplo, varios sprites que utilizan las mismas poses pueden calcular con este reloj qué pose les corresponde cada cuatro frames.

Así todos cambian al mismo tiempo y solicitan la misma pose. La primera solicitud puede necesitar cargarla; las demás la reutilizan sin programar otra carga de sus gráficos. Esto ahorra transferencias DMA y datos enviados por frame.

Si cada sprite llevara un reloj independiente, podrían terminar usando poses distintas de la misma animación al mismo tiempo y necesitar más cargas y espacio de VRAM.

<code>DX_SyncTimer</code> se detiene durante la pausa y cuando se congela la acción, para que las animaciones sincronizadas también se detengan.

== Carga de gráficos: GraphicsChange ==

<code>GraphicsChange</code> guarda en RAM una lista de solicitudes de carga. Durante NMI se recorren esas solicitudes y se copian sus datos a VRAM.

=== Variables de la lista ===

En esta tabla, '''V''' es el valor de <code>!VRAMTransferSize</code>: 64 por defecto. Las cuatro tablas de solicitudes reservan V bytes cada una; con entradas de 2 bytes, ese valor deja espacio para 32 solicitudes. Junto con el contador, reservan <code>1 + 4 × V</code> bytes: 257 por defecto.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Cantidad de solicitudes pendientes. El valor 0 indica que la lista está vacía.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 por defecto || 2 || Dirección de origen de cada solicitud, sin el banco.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 por defecto || 2 reservados; banco de 1 byte || Banco del origen.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 por defecto || 2 || Cantidad de bytes que se copiarán.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 por defecto || 2 || Dirección de destino en VRAM.
|}

Las tablas mantienen el mismo orden: la primera entrada de cada tabla pertenece a la primera solicitud, la segunda a la segunda, etc. Cada entrada de estas tablas ocupa 2 bytes, por lo que se avanza con desplazamientos de <code>$00</code>, <code>$02</code>, <code>$04</code>, etc.

Estos nombres representan direcciones de RAM calculadas en <code>DXDefines.asm</code>. Sus direcciones pueden cambiar según la configuración y las funcionalidades habilitadas.

=== Añadir una solicitud ===

La macro <code>%TransferToVRAM()</code> realiza los siguientes pasos:

# Calcula cuántos bytes habría en total al añadir la nueva carga a <code>DX_Dynamic_CurrentDataSend</code>.
# Compara el resultado con <code>DX_Dynamic_MaxDataPerFrame</code>. Si lo supera, devuelve el carry desactivado y no añade la solicitud.
# Utiliza <code>DX_PPU_VRAM_Transfer_Length</code> para encontrar la siguiente entrada y aumenta ese contador en 1.
# Guarda el origen, banco, cantidad de bytes y destino en las tablas.
# Actualiza <code>DX_Dynamic_CurrentDataSend</code> con los bytes de la carga y devuelve el carry activado.

<code>%ForcedTransferToVRAM()</code> guarda los mismos datos, pero no comprueba el límite de bytes. Las variantes <code>FromAddr</code> y <code>Resource</code> facilitan obtener el origen desde una dirección completa o desde los defines de un recurso.

Añadir una solicitud no copia los gráficos inmediatamente: deja la información preparada para NMI.

=== Ejecutar las solicitudes durante NMI ===

La rutina <code>VRAMDMA</code>:

# Lee <code>DX_PPU_VRAM_Transfer_Length</code>. Si es 0, termina porque no hay solicitudes.
# Calcula el desplazamiento de la última entrada: <code>(Length - 1) × 2</code>.
# Lee su origen, banco y cantidad de bytes, y los coloca en los registros de DMA.
# Escribe el destino de VRAM en <code>$2116-$2117</code> e inicia la transferencia mediante <code>$420B</code>.
# Retrocede 2 bytes para procesar la solicitud anterior. Repite hasta completar la primera.
# Escribe 0 en <code>DX_PPU_VRAM_Transfer_Length</code> para indicar que la lista está vacía.

'''La lista se ejecuta del final al inicio.''' No hace falta borrar todos sus datos al terminar: al quedar su largo en 0, la próxima solicitud volverá a utilizar la primera entrada.

=== Animaciones con un destino fijo ===

El código de una animación debe:

# Elegir la imagen que corresponde al paso actual.
# Calcular su dirección de origen.
# Solicitar la copia al destino de VRAM de la animación.
# Comprobar el carry. Si se rechaza la carga, conservar la imagen anterior y volver a intentarlo.

El destino puede ser siempre el mismo. Lo que cambia es la imagen que se copia allí; la lista de transferencias no decide cuándo debe avanzar la animación.

Puedes ver un código completo en [[es/Dynamic_Xtreme_UberASM_guide#Crear_animaciones_de_gráficos|Crear animaciones de gráficos de la guía de UberASM]].

=== Carga de una pose dinámica ===

La carga de una pose utiliza la caché para no repetir transferencias de gráficos que ya están disponibles:

# Busca el ID en la tabla hash.
# Si ya está registrado, actualiza su tiempo de uso y no añade otra carga.
# Si no está, comprueba la cantidad de bytes y busca un espacio adecuado en el mapa de VRAM.
# Elige qué poses pueden reemplazarse, teniendo en cuenta su tiempo sin uso y el espacio que necesita la nueva.
# Actualiza las tablas de la caché y el mapa.
# <code>DynamicRoutine</code> divide los datos de la pose en las transferencias necesarias.
# NMI ejecuta esas transferencias.

Cada paso se desarrolla en [[#Sprites_dinámicos:_DynamicPoses|Sprites dinámicos: DynamicPoses]], incluyendo la búsqueda por hash, el mapa, la política de reemplazo y la división de la carga en filas.

== Carga y asignación de paletas: PalettesChange ==

El sistema distingue dos valores:

* '''ID de paleta:''' identifica los colores guardados en ROM.
* '''Destino de pantalla:''' indica qué paleta de CGRAM utilizará esos colores.

La asignación automática permite compartir colores entre sprites sin exigir un destino fijo para cada uno.

=== Lista de cargas a CGRAM ===

En esta tabla, '''C''' es <code>!CGRAMTransferSize</code>: 64 por defecto. El conjunto reserva <code>1 + 7 × C</code> bytes, es decir, 449 con ese valor. Aunque <code>SourceBNK</code> reserva 2 × C bytes, el código utiliza un byte de banco por solicitud.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Índice de la última solicitud pendiente. <code>$FF</code> indica una lista vacía; 0 indica que hay una solicitud.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 por defecto || 2 || Dirección de origen, sin el banco.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 reservados por defecto || 1 utilizado por solicitud || Banco del origen.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 por defecto || 2 || Cantidad de bytes que se copiarán. Cada color ocupa 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 por defecto || 1 || Primer color de destino en CGRAM.
|}

Durante NMI, <code>CGRAMDMA</code>:

# Comienza por la última solicitud pendiente.
# Configura DMA con el origen y la cantidad de bytes de esa solicitud.
# Selecciona el primer color mediante <code>$2121</code> y realiza la copia.
# Continúa con las solicitudes anteriores.
# Al terminar, escribe <code>$FF</code> en <code>DX_PPU_CGRAM_Transfer_Length</code>.

Las macros <code>TransferPalette</code> también actualizan las copias de colores y el estado de efectos:

* '''Sin efecto global:''' solicitan la carga y actualizan los buffers de SMW. Así el juego no vuelve a utilizar colores anteriores durante la animación de victoria del goal.
* '''Con efecto global:''' guardan los colores originales y preparan el estado necesario para aplicarles el efecto antes de enviarlos a CGRAM.

=== Asignación automática ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || Guarda el ID asignado a cada destino. <code>$FFFF</code> indica una entrada libre y <code>$FFFE</code> una reservada.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protege cada destino del reemplazo automático mientras está en uso.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; un bit por paleta de sprites || Indica qué paletas de sprites están asignadas con efecto global habilitado. Esta condición también se compara al compartir una asignación.
|}

La búsqueda sigue este orden:

# Reutilizar una asignación con el mismo ID y una condición de efecto compatible.
# Si no existe, utilizar una entrada libre.
# Si no hay entradas libres, reemplazar una que no esté reservada y cuyo temporizador sea 0.
# Si no encuentra ninguna, indicar que la asignación falló.

Mientras el recurso utiliza la paleta, mantiene su temporizador en 2. Llegar a 0 no borra los colores: la asignación puede reutilizarse si otro recurso todavía no la reemplazó.

=== Asignación manual y versión ===

* '''Manual con carga:''' el código elige el destino y solicita sus colores.
* '''Manual sin carga:''' el código elige el destino y utiliza los colores que ya estaban preparados.
* '''Versión:''' selecciona una entrada de la lista de paletas del DynamicInfo. La última versión procesada permite comprobar si esa selección cambió.

Dos recursos que elijan el mismo destino con colores distintos deben coordinarse. Mantener la protección de una paleta no significa volver a cargar sus colores.

== Dibujo de poses: DrawingSystem ==

El dibujo prepara las piezas de una pose en OAM: qué tiles se muestran, dónde se colocan y qué propiedades utilizan. Los datos gráficos deben estar en VRAM.

=== Pasos del dibujo ===

# Busca la rutina y los datos de la pose mediante <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code> y <code>TableOffset</code>.
# Obtiene la cantidad de piezas desde <code>NumberOfTilesMinus1</code>.
# Calcula la posición de cada tile usando la posición del sprite, sus desplazamientos y los volteos que correspondan.
# Comprueba si la pieza puede verse y si queda espacio de OAM.
# Escribe su posición, número de tile, propiedades y tamaño en los buffers OAM.

El número de tile depende del dibujo:

{| class="wikitable"
! Caso !! Cómo se obtiene el tile
|-
| Pose dinámica || Se ajusta al lugar de VRAM donde quedaron cargados sus gráficos.
|-
| Pose estática || Se utiliza su número de tile fijo.
|-
| Pose que utiliza un tile común || El código debe preparar <code>!Tile</code> antes de llamar al dibujo.
|}

=== Prioridad y espacio disponible ===

* En '''LoROM''', el sistema lleva su propio control de entradas OAM disponibles.
* En '''SA-1''', utiliza la integración con MaxTile.
* La '''prioridad de dibujo''' organiza las piezas de sprites. No es la misma propiedad que determina si un tile queda delante o detrás de las capas.
* Los '''límites por línea de pantalla''' de SNES siguen existiendo. Tener una pose cargada no garantiza que puedan verse todas sus piezas.

== Jugador y Yoshi ==

=== PlayerFeatures ===

El jugador original tiene rutinas propias para elegir y cargar las piezas de sus poses. <code>PlayerFeatures</code> permite integrar ese trabajo con las cargas de Dynamic Xtreme y cambiar el origen de sus gráficos y paletas.

Con el formato original, el juego sigue eligiendo las piezas de la pose. La rutina obtiene sus direcciones desde el origen configurado y compara esas direcciones con las anteriores para cargar las que hayan cambiado.

Estas cargas utilizan transferencias forzadas y sus bytes también cuentan para las solicitudes normales posteriores. Así conservan su prioridad sin quedar fuera de la contabilidad del sistema.

La paleta del jugador tiene un tratamiento especial: combina colores y selecciones del propio juego con el origen personalizado. No funciona simplemente como sustituir una paleta completa de un sprite cualquiera.

El soporte para jugadores personalizados permite que otros sistemas administren de otra forma sus poses y dibujo. No convierte automáticamente cualquier spritesheet al formato del jugador original.

=== YoshiFeatures ===

Yoshi también carga sus gráficos por piezas. <code>YoshiFeatures</code> permite cambiar su origen manteniendo la organización que esperan sus rutinas.

El código calcula qué partes necesita y prepara sus cargas a los destinos correspondientes de VRAM. Como las del jugador, estas cargas tienen un tratamiento prioritario.

Esta opción necesita <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad. No permite evitar un conflicto del sistema del jugador habilitando únicamente las funciones de Yoshi.

== Memoria y optimizaciones ==

=== Free7E2000 ===

SMW mantiene en RAM gráficos originales del jugador, Yoshi y ciertas animaciones. En ROMs sin SA-1, esta opción adapta las cargas para leer esos datos desde ROM.

Dynamic Xtreme aprovecha la RAM recuperada para sus variables internas. No es un espacio que quede libre para que cualquier otro código escriba encima.

SA-1 utiliza otras direcciones y desactiva esta opción. Los rangos están en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Espacios de RAM utilizados]].

=== ControllerOptimization ===

Esta opción mueve el procesamiento del control desde NMI a la parte de game mode. El objetivo es dejar más tiempo para las actualizaciones de pantalla, no añadir un frame de retraso ni cambiar los botones que recibe el juego.

=== FixedColorOptimization ===

El color fijo se utiliza en las mezclas de color de la consola. Para actualizarlo, el juego prepara sus componentes y los envía al registro correspondiente.

La optimización reemplaza esa preparación por una secuencia más corta. El color sigue enviándose a la consola, pero necesita menos trabajo durante NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic utiliza listas llamadas stripe images para actualizar partes de los mapas de tiles. Esas listas incluyen tanto los datos como la información sobre sus destinos.

La versión integrada de la optimización de Kevin prepara fuera de NMI parte del ajuste de esos destinos. Así deja menos trabajo de preparación para el momento de la transferencia.

Esta opción sustituye el uso del parche original por separado. Además, no debe desinstalarse después de instalarla; hay que tenerlo en cuenta antes de activarla.

=== StatusBarOptimization ===

La barra de estado original actualiza zonas concretas de VRAM. Esta opción prepara sus transferencias de forma más directa, reduciendo la configuración de DMA que necesita hacer durante NMI.

No añade una barra nueva. Modifica la actualización de la original y, por eso, entra en conflicto con recursos que la reemplazan, modifican o eliminan.

== Sprites dinámicos: DynamicPoses ==

El sistema funciona como una '''caché de poses en VRAM'''. No reserva una copia de los gráficos para cada sprite: guarda la pose y permite que la reutilicen todos los recursos que la necesiten.

* Una pose se carga una sola vez mientras permanezca en la caché.
* Las siguientes solicitudes actualizan su tiempo de último uso, sin añadir otra carga de sus gráficos.
* La pose no se borra cuando un recurso deja de utilizarla. Permanece allí hasta que se necesite su espacio y se elija reemplazarla.
* Si fue reemplazada y vuelve a solicitarse, tendrá que cargarse otra vez.

La elección no depende de cuánto tiempo lleva la pose desde que se cargó, sino de '''cuánto tiempo lleva sin utilizarse''' y de si su espacio sirve para la pose nueva.

=== Tres valores distintos ===

{| class="wikitable"
! Valor !! Qué identifica
|-
| ID de pose || La pose instalada. Tiene 16 bits y permite consultar sus datos en ROM.
|-
| Índice de la tabla hash || La entrada de RAM donde se registró la pose. Va de 0 a 127.
|-
| Bloque de VRAM || ID de una de las 128 posiciones para tiles de 16×16 que caben en el espacio de VRAM de sprites. Se numeran de izquierda a derecha y de arriba abajo, desde 0 hasta 127. Para una pose que ocupa varios bloques, se guarda el ID de su primer bloque.
|}

El índice de la tabla hash y el bloque de VRAM no tienen por qué coincidir. Una entrada de la tabla puede registrar una pose que empieza en cualquier bloque permitido.

=== Tablas de las poses registradas ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Cantidad de poses registradas.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Cantidad de poses registradas para cada hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || ID completo de la pose de cada entrada. <code>$FFFF</code> indica una entrada libre.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Bloque de VRAM donde comienza cada pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || Valor de <code>DX_Timer</code> de su último uso.
|}

Estas tablas ocupan '''769 bytes''' en RAM. Guardan las poses registradas durante el juego; las tablas generadas desde el DynamicInfo describen, en cambio, todas las poses instaladas.

=== Cómo se busca una pose ===

La rutina <code>DynamicPoseHashmap_FindPose</code> utiliza una tabla hash de 128 entradas. El hash permite elegir dónde empezar a buscar:

<pre>
hash = ID de pose AND $007F
</pre>

Dos IDs diferentes pueden tener el mismo hash. Por ejemplo, <code>$0005</code> y <code>$0085</code> producen <code>$05</code>. Por eso el hash no basta para confirmar que la pose está cargada: también se compara el ID completo.

La búsqueda sigue estos pasos:

# Guarda el ID solicitado y calcula su hash.
# Si <code>DX_Dynamic_Pose_Length</code> es 0, no hay poses registradas y la búsqueda termina.
# Consulta <code>DX_Dynamic_Pose_HashSize[hash]</code>. Si es 0, ninguna pose registrada tiene ese hash y también termina.
# Comienza por la entrada cuyo índice coincide con el hash.
# Lee el ID de esa entrada. Si coincide con el solicitado, encontró la pose.
# Si no coincide, continúa con la siguiente entrada de la secuencia de búsqueda.

La secuencia avanza '''15 entradas por intento''' y vuelve al comienzo al superar 127:

<pre>
siguiente índice = (índice actual + 15) AND $7F
</pre>

Con 128 entradas, ese paso permite visitar todas las posiciones antes de repetir una. Para el hash <code>$05</code>, el comienzo de la secuencia es:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

==== El contador de poses de cada hash ====

Cada hash tiene su propio contador en <code>DX_Dynamic_Pose_HashSize</code>. Por ejemplo, si hay dos poses registradas cuyo ID produce el hash <code>$05</code>, la entrada <code>DX_Dynamic_Pose_HashSize+$05</code> contiene 2.

Ese número indica '''cuántas poses con ese hash existen''', no cuántas posiciones hay que recorrer. La búsqueda utiliza una copia temporal del contador:

# Comienza con la cantidad de poses registrada para el hash solicitado.
# Recorre las posiciones de la secuencia hasta encontrar el ID solicitado o haber comprobado esa cantidad de poses con el mismo hash.
# Cada vez que encuentra una pose con ese hash, pero con otro ID, resta 1 al contador temporal.
# Las posiciones libres y las poses de otros hashes no descuentan nada: continúa buscando.
# Si el contador temporal llega a 0 sin encontrar el ID, la pose solicitada no está registrada y la búsqueda termina.

El contador de <code>DX_Dynamic_Pose_HashSize</code> no se modifica durante esta búsqueda. Solo se actualiza al añadir o retirar poses de la caché.

Por ejemplo, se busca <code>$0105</code>, que produce el hash <code>$05</code>, y el contador de ese hash vale 2:

{| class="wikitable"
! Posición visitada !! ID guardado !! Hash del ID !! Poses del hash $05 que faltan por comprobar
|-
| <code>$05</code> || <code>$0005</code> || <code>$05</code> || 1: tiene el mismo hash, pero no es el ID solicitado.
|-
| <code>$14</code> || <code>$0014</code> || <code>$14</code> || 1: es otro hash, así que no se descuenta.
|-
| <code>$23</code> || <code>$0085</code> || <code>$05</code> || 0: ya se comprobaron las dos poses con ese hash. <code>$0105</code> no está registrada.
|}

Lo habitual es que haya una o dos poses por hash. Esto permite resolver la búsqueda con pocas comprobaciones y un coste normalmente cercano a <code>O(1)</code>. No significa que siempre se visiten solo una o dos posiciones: puede haber entradas de otros hashes entre ellas. Con muchas colisiones, el recorrido puede ser más largo.

'''Una entrada libre no termina la búsqueda.''' Puede haber quedado vacía al reemplazar una pose y existir otra del mismo hash más adelante. El contador permite saber cuándo ya se comprobaron todas las poses de ese hash, incluso si hay huecos entre ellas.

==== Cuando encuentra la pose ====

<code>TakeDynamicRequest</code>:

# Obtiene el índice de la entrada encontrada.
# Escribe el valor actual de <code>DX_Timer</code> en <code>DX_Dynamic_Pose_TimeLastUse</code> para esa entrada.
# Devuelve el éxito de la solicitud, sin volver a programar la carga de sus gráficos.

Así todos los recursos que solicitan ese ID utilizan la misma pose y la mantienen protegida. No importa si el recurso es un sprite normal, cluster, extended u otro código que utiliza el sistema.

Esto también evita duplicar una carga dentro del mismo ciclo: cuando la primera solicitud se acepta, la pose ya queda registrada aunque la transferencia física se vaya a realizar durante NMI.

=== Cuando la pose no está registrada ===

<code>TakeDynamicRequest</code> continúa con la preparación de una carga nueva:

# Consulta <code>PoseSize</code> y calcula <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# Si supera <code>DX_Dynamic_MaxDataPerFrame</code>, termina con fallo, sin cambiar las poses existentes.
# Consulta <code>Pose16x16Blocks</code> para saber cuántos bloques necesita.
# Llama a <code>VRAMMap_GetBestSlot</code> para buscar un espacio adecuado.
# Si no existe un espacio utilizable, termina con fallo.
# Retira del mapa y de la tabla hash las poses que ocupen el espacio elegido.
# Busca una entrada libre de la tabla hash y registra la pose nueva.
# Actualiza el mapa de VRAM y el contador de datos del frame.
# Llama a <code>DynamicRoutine</code> para añadir las transferencias.

El presupuesto se comprueba antes de reemplazar poses. Si la nueva carga no cabe en el frame, no se libera espacio para una solicitud que no se puede atender.

==== Añadir y quitar entradas de la tabla hash ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> busca una entrada cuyo ID sea <code>$FFFF</code>, siguiendo la misma secuencia de pasos de 15.
* <code>DynamicPoseHashmap_Add</code> guarda el ID y su tiempo de uso, aumenta <code>DX_Dynamic_Pose_Length</code> y aumenta el contador de su hash.
* <code>DynamicPoseHashmap_Remove</code> escribe <code>$FFFF</code> en el ID retirado y reduce ambos contadores.

Retirar una entrada no borra por sí solo los píxeles de VRAM. Indica que esa pose dejó de estar disponible en la caché; las nuevas transferencias sobrescribirán el espacio elegido.

=== Cómo se representa el mapa de VRAM ===

El mapa representa '''128 posiciones de tiles de 16×16 en la VRAM de sprites''', numeradas de izquierda a derecha y de arriba abajo. Cada bloque es una de esas posiciones, no un tramo de 128 bytes contiguos.

Un tile de 16×16 está formado por cuatro tiles de 8×8 distribuidos en dos filas. El mapa administra las posiciones que ocupa la pose; la distribución de sus datos para cargarlos se resuelve después en <code>DynamicRoutine</code>.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Posición donde comienza la sección. El bit <code>$80</code> indica que está restringida: ese espacio no se utiliza para poses dinámicas.
|-
| <code>DX_Dynamic_Tile_Size</code>, también llamada <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || Si el bit <code>$80</code> está activo, los otros bits guardan la cantidad de posiciones de la sección menos uno. Si está desactivado, guardan el índice hash de la pose que ocupa la sección. Para saber si el espacio está restringido, se consulta <code>Offset</code>.
|}

Estas dos tablas ocupan '''256 bytes'''. Junto con las tablas de poses, el administrador utiliza '''1025 bytes''' de RAM, sin contar las listas de transferencias ni las scratch de trabajo.

=== Secciones del mapa ===

Una sección agrupa posiciones consecutivas del mapa que están restringidas, libres o utilizadas por una pose. Su información se guarda en '''la primera y la última posición'''. Esto permite saltar de una sección a la anterior sin revisar todas sus posiciones intermedias.

Los siguientes ejemplos muestran tres estados posibles para una sección de 6 posiciones, de <code>$20</code> a <code>$25</code>. Son casos alternativos, no tres secciones que ocupen el mismo espacio a la vez.

==== Ejemplo 1: sección restringida ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$A0</code> || <code>$80</code> indica restringida y <code>$20</code> indica dónde comienza.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || La sección tiene 6 posiciones: <code>($85 AND $7F) + 1 = 6</code>.
|}

Aunque el bit alto de <code>Size</code> esté activo, '''no es espacio libre para poses dinámicas''': el bit de restricción en <code>Offset</code> hace que se descarte. No se evalúa como una pose que pueda reemplazarse.

<code>DynamicPoseSpaceConfig</code> utiliza este tipo de sección para excluir las partes de SP1-SP4 que no deben utilizar los sprites dinámicos.

==== Ejemplo 2: sección libre ====

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || Comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$85</code> || El bit <code>$80</code> indica el tamaño de una sección libre: <code>$05 + 1 = 6</code> posiciones.
|}

Esta sección sí está disponible. Puede alojar una pose que necesite hasta 6 posiciones; si se coloca una de 4, las otras 2 quedan como otra sección libre.

==== Ejemplo 3: sección utilizada por una pose ====

Supongamos que una pose de 6 bloques está registrada en la entrada hash <code>$07</code> y ocupa las posiciones <code>$20</code> a <code>$25</code>:

{| class="wikitable"
! Entradas de las tablas !! Valor !! Significado
|-
| <code>DX_Dynamic_Tile_Offset+$20</code> y <code>+$25</code> || <code>$20</code> || La sección comienza en <code>$20</code> y no está restringida.
|-
| <code>DX_Dynamic_Tile_Size+$20</code> y <code>+$25</code> || <code>$07</code> || El bit <code>$80</code> está desactivado: <code>$07</code> es el índice hash de la pose, no su cantidad de bloques.
|}

Para conocer la cantidad de posiciones y el tiempo sin uso:

# Se lee el ID de la pose en <code>DX_Dynamic_Pose_ID+$0E</code>. Se utiliza <code>$0E</code> porque cada ID ocupa 2 bytes y <code>$07 × 2 = $0E</code>.
# Con ese ID se consulta <code>Pose16x16Blocks</code>, que en este ejemplo contiene 6.
# Se consulta <code>DX_Dynamic_Pose_TimeLastUse+$0E</code> para calcular cuánto lleva sin utilizarse.

La entrada <code>DX_Dynamic_Pose_Offset+$07</code> guarda <code>$20</code>, relacionando esa pose registrada con su posición en VRAM.

=== Recorrido y búsqueda de espacio ===

<code>VRAMMap_GetBestSlot</code> comienza por la posición de tile de 16×16 <code>$7F</code>. Para recorrer el mapa:

# Lee <code>DX_Dynamic_Tile_Offset</code> de la posición actual.
# Obtiene el comienzo de la sección con <code>Offset AND $7F</code>.
# Evalúa esa sección y los espacios que pueda formar con otras secciones contiguas.
# Pasa a la posición <code>comienzo de la sección - 1</code>, que es la última posición de la sección anterior.
# Repite hasta llegar al comienzo del mapa.

Por ejemplo, si las últimas secciones comienzan en <code>$70</code>, <code>$60</code> y <code>$50</code>:

{| class="wikitable"
! Posición visitada !! Comienzo leído de Offset !! Próxima posición
|-
| <code>$7F</code> || <code>$70</code> || <code>$6F</code>
|-
| <code>$6F</code> || <code>$60</code> || <code>$5F</code>
|-
| <code>$5F</code> || <code>$50</code> || <code>$4F</code>
|}

Así recorre '''secciones completas''', no cada tile intermedio.

==== Qué se evalúa durante el recorrido ====

El espacio candidato puede ser '''una sección o varias secciones contiguas'''. En cada paso se comprueba:

* Si hay una sección restringida, no se utiliza ni se combina a través de ella.
* Si hay una pose protegida por su uso reciente, tampoco puede formar parte del espacio.
* Si el candidato todavía es pequeño, se puede continuar con una sección contigua para completar la cantidad de bloques necesaria.
* Si ya cabe la pose, se compara el candidato con el mejor encontrado: primero por su score de tiempo sin uso y después por el espacio suficiente más pequeño.

No se elige una sección solo por contener la pose con más tiempo sin uso. El '''espacio completo''' debe permitir cargar la pose nueva. La puntuación de varias secciones combinadas depende de la pose utilizada más recientemente dentro de ese espacio.

Durante la búsqueda se conservan estos datos temporales:

{| class="wikitable"
! Datos de trabajo !! Bytes totales !! Bytes por valor !! Para qué se usan
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 por campo || Comienzo, score y cantidad de bloques del espacio candidato actual.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 por campo || Los mismos campos para el mejor espacio encontrado.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Cantidad de bloques que necesita la pose nueva.
|}

Estos nombres utilizan scratch de trabajo, no RAM persistente adicional.

=== Política de reemplazo: tiempo sin uso y espacio suficiente ===

El sistema no elige simplemente la pose que se cargó primero. Utiliza el tiempo transcurrido desde su '''último uso''':

<pre>
tiempo sin uso = DX_Timer - TimeLastUse de la pose
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> obtiene el tamaño y una puntuación para cada región:

{| class="wikitable"
! Caso !! Puntuación y tratamiento
|-
| Región libre || <code>$FF</code>. Se favorece frente a regiones ocupadas.
|-
| Región ocupada || Tiempo sin uso, limitado a <code>$FE</code>.
|-
| Tiempo sin uso de 0 o 1 || No se puede reemplazar: la pose sigue protegida.
|-
| Región restringida || Se descarta: ese espacio no se utiliza para poses dinámicas.
|}

La protección exige '''al menos dos avances de <code>DX_Timer</code> sin utilizar la pose'''. Cada recurso que vuelve a solicitarla actualiza su tiempo de uso y vuelve a protegerla.

==== Por qué no siempre se reemplaza la pose con más tiempo sin uso ====

La pose nueva necesita espacio suficiente y contiguo. Un espacio pequeño no sirve por sí solo, aunque lleve mucho tiempo sin utilizarse.

Por ejemplo, para una pose nueva de 4 bloques:

{| class="wikitable"
! Espacio candidato !! Tiempo sin uso !! ¿Sirve?
|-
| Pose A: 2 bloques, sin espacio contiguo utilizable || 20 || No: solo deja 2 bloques.
|-
| Pose B: 4 bloques || 8 || Sí: puede alojar la pose nueva.
|}

En este caso se puede reemplazar B y conservar A. A lleva más tiempo sin uso, pero su espacio no permite atender la solicitud.

Si dos o más regiones contiguas pueden reemplazarse, el sistema puede considerarlas juntas. Para esa combinación:

* Suma sus cantidades de bloques.
* Utiliza la '''menor puntuación''' de las regiones combinadas, es decir, el menor tiempo sin uso.
* Si una está restringida o protegida, no puede utilizarla para completar el espacio.

Así una pose usada recientemente no puede quedar sobrescrita por combinarla con otra que lleva mucho tiempo sin uso.

==== Elegir entre candidatos válidos ====

# El candidato debe tener al menos la cantidad de bloques solicitada.
# Se prefiere la puntuación más alta: espacio libre o mayor tiempo sin uso.
# Si las puntuaciones son iguales, se prefiere el candidato con menos bloques, siempre que la pose quepa.
# Si puntuación y tamaño también coinciden, se conserva el candidato que ya se había elegido.

Las regiones se combinan durante la búsqueda cuando el candidato todavía es demasiado pequeño. No se juntan todas las regiones reemplazables sin tener en cuenta el tamaño solicitado.

=== Reemplazar y dividir la región elegida ===

Una vez elegido el espacio:

# <code>VRAMMap_RemovePosesInSpace</code> recorre sus regiones y retira de la tabla hash las poses que haya que reemplazar.
# <code>VRAMMap_RemoveSpace</code> representa el espacio elegido como una región libre, actualizando sus extremos.
# Se busca una entrada hash libre y se guarda el bloque de comienzo en <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registra la pose.
# <code>VRAMMap_AddPoseInSpace</code> escribe el índice hash de la pose y el comienzo de su región en el primer y último bloque.
# Si sobran bloques, crea otra región libre con el resto.

Si una región de 6 bloques aloja una pose de 4, quedan una región ocupada de 4 y una libre de 2. No se mueven las demás poses para compactar VRAM.

=== DynamicRoutine: preparar las transferencias de la pose ===

En este punto ya se eligió el espacio y se registró la pose. <code>DynamicRoutine</code> convierte esa asignación en solicitudes de transferencia.

Utiliza estos datos:

{| class="wikitable"
! Dato !! Cantidad consultada por pose !! Para qué sirve
|-
| Bloque de comienzo || 1 byte || Lugar elegido por el mapa de VRAM.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes de una tabla de 256 bytes || Convierte uno de los 128 bloques en un desplazamiento de VRAM.
|-
| <code>PoseResource</code> || 3 bytes || Dirección completa de los datos de la pose en ROM.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: dos valores de 2 || Cantidad de bytes del primer y del segundo tramo.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || Desplazamiento de VRAM para el segundo tramo.
|}

==== Convertir el bloque en una dirección de VRAM ====

Los bloques de 16×16 no se convierten simplemente en un desplazamiento lineal de bytes. Cada uno utiliza tiles de 8×8 distribuidos en las filas de VRAM.

<code>OffsetToVRAMOffset</code> contempla esa distribución. Por ejemplo:

{| class="wikitable"
! Bloque !! Desplazamiento !! Dirección de VRAM
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

Estas direcciones de VRAM están expresadas en palabras de 2 bytes, no en bytes. La rutina suma la base <code>$6000</code> utilizada para los gráficos de sprites.

==== Procesar los tramos y sus filas ====

# Obtiene el origen desde <code>PoseResource</code>.
# Procesa los bytes del primer tramo mediante <code>DynamicRoutineLine</code>.
# Si el segundo tramo tiene tamaño 0, termina.
# Si existe, adelanta el origen la cantidad de bytes del primer tramo.
# Suma <code>PoseSecondLineOffset</code> al desplazamiento de VRAM y procesa el segundo tramo.

<code>DynamicRoutineLine</code> divide cada tramo según las filas y el punto de comienzo. Para un destino V expresado en palabras de VRAM, prepara:

<pre>
Final de la primera fila = (V + $0100) AND $FF00
Bytes hasta ese final = (final de la primera fila - V) × 2
Destino de la segunda parte = final de la primera fila + $0100
Bytes de la segunda parte de un grupo = $0200 - bytes de la primera
</pre>

Los tamaños son cantidades de bytes, mientras que los destinos de VRAM están expresados en palabras. Por eso se multiplica por 2 al calcular cuántos datos caben hasta el final de una fila.

La rutina utiliza tres recorridos:

* <code>.EndLine</code>: añade una solicitud final con los bytes restantes.
* <code>.TwoLinesWithEndLine</code>: añade dos solicitudes para los datos restantes, cada una con su destino y cantidad de bytes.
* <code>.TwoLines</code>: añade dos solicitudes que suman <code>$0200</code> bytes, avanza el origen y los destinos y repite con los datos que faltan.

Hay un caso directo antes del recorrido general: si el destino comienza en un límite de <code>$0100</code> palabras y el tramo tiene al menos <code>$0200</code> bytes, la rutina utiliza <code>.EndLine</code> para preparar la copia del tramo completo en una solicitud.

Por ejemplo, un tramo de <code>$0200</code> bytes que comienza en <code>$6020</code> se divide así:

{| class="wikitable"
! Solicitud !! Origen !! Destino VRAM !! Bytes
|-
| Primera || Comienzo del tramo || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Segunda || Comienzo del tramo + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Las dos solicitudes copian los 512 bytes del tramo, respetando los destinos que calcula la distribución de filas. No son dos copias completas de la pose.

Cada solicitud utiliza estas tablas:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Por cada solicitud añadida aumenta <code>DX_PPU_VRAM_Transfer_Length</code>.

La cantidad total de bytes de la pose ya se comprobó y se añadió a <code>DX_Dynamic_CurrentDataSend</code> en <code>TakeDynamicRequest</code>. Esta parte divide esa carga en transferencias; no vuelve a contar la pose completa por cada solicitud.

<code>DynamicRoutine</code> '''no ejecuta DMA'''. Deja las solicitudes preparadas para que <code>VRAMDMA</code> las copie durante NMI.

=== Qué conserva el sprite ===

Las rutinas de sprites guardan el índice hash de la pose utilizable, no una copia independiente de sus gráficos. Ese índice permite consultar su bloque de VRAM y mantener actualizado su tiempo de uso.

Si una pose nueva no puede cargarse:

* Si existe una pose anterior válida, se mantiene y se actualiza su tiempo de uso para protegerla.
* Si nunca hubo una pose válida, no se debe dibujar como si la solicitud hubiera tenido éxito.
* En las llamadas con soporte para mantener la anterior, el carry puede indicar que todavía hay una pose utilizable aunque no se haya completado el cambio.

La animación y el movimiento siguen siendo responsabilidad del sprite. La caché se ocupa de reutilizar o preparar los gráficos solicitados.

== Efectos de paleta: PalettesEffects ==

El sistema conserva los colores originales para poder cambiar de efecto, combinarlo con otro o volver a la paleta sin efecto. No debe utilizar el resultado ya afectado como si fuera la paleta original.

=== Buffers de colores ===

{| class="wikitable"
! Variable o buffer !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 por color || Colores de base en formato SNES, con 2 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 por color || Base separada en rojo, verde y azul, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 por color || Base separada en tono, saturación y luminosidad, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 por color || Resultado en formato SNES, listo para solicitar su copia a CGRAM. Corresponde al buffer de paletas del juego.
|}

=== Indicadores de cada paleta ===

Cada bit de estos indicadores corresponde a una paleta. Las variables <code>BG</code> cubren 0-7 y las <code>SP</code> cubren 8-F.

{| class="wikitable"
! Variables !! Bytes totales !! Bytes por valor !! Qué indican
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> y <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si ya se preparó la base de colores en formato SNES.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> y <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparado el resultado del efecto global.
|}

Estos indicadores evitan repetir conversiones y cálculos que siguen siendo válidos.

=== Preparar una base ===

# Se comprueba si la paleta ya tiene una base registrada.
# Si no la tiene, se obtienen los colores del buffer del juego. Una carga explícita, como <code>TransferPalette</code>, puede proporcionar esa base directamente.
# Se comprueba si el efecto necesita RGB o HSL.
# Si falta esa conversión, se prepara y se marca como disponible.

Si solo cambia el efecto, la base puede seguir siendo válida. Si cambian los colores originales, las llamadas de carga actualizan la base e invalidan las conversiones y resultados que deben calcularse otra vez.

=== Datos de un efecto ===

El ID permite consultar las tablas generadas durante la instalación:

* <code>Types</code>: cálculo que debe realizarse.
* <code>Value1</code>, <code>Value2</code> y <code>Value3</code>: valores de los canales o dirección de la paleta de destino de una transición.
* <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code>: cuánto se aplica cada cambio.

Los canales utilizan valores de 0 a 31. Los ratios van de 0 a 127: 0 conserva el origen y 127 aplica por completo el cambio elegido.

Los cálculos se realizan fuera de NMI. NMI realiza la transferencia de los colores resultantes.

=== Efecto global ===

{| class="wikitable"
! Variable !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selecciona el efecto global. El valor 0 permite restaurar los colores de base.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 0-7 que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 8-F que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Guarda el último ID global procesado por cada paleta.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controla la participación del color fijo y el color 0,0.
|}

Para cada paleta habilitada, el administrador:

# Comprueba si necesita actualizar el resultado del efecto.
# Prepara la base RGB o HSL si todavía falta.
# Calcula el efecto si el resultado anterior ya no sirve.
# Prepara los colores en formato SNES y solicita su transferencia.
# Confirma el ID procesado cuando la carga correspondiente se acepta.

Si se mantiene el mismo efecto y no cambió la base, no hace falta calcularlo otra vez. Al cambiar el ID global se invalidan los resultados anteriores, no necesariamente las bases RGB y HSL.

El ID global 0 también requiere una actualización: el sistema debe cargar de nuevo los colores de base para quitar el efecto anterior.

=== Efecto local y concatenación ===

Un recurso puede tener un efecto propio y recibir también el global. Por ejemplo, un sprite puede cambiar de tono y después oscurecerse junto con el nivel.

El orden es:

# Preparar el resultado del efecto local.
# Utilizarlo como base para el efecto global mediante la llamada de concatenación.
# Calcular el efecto global sobre esa base.
# Cargar el resultado combinado, sin mostrar antes la versión que solo tiene el efecto local.

* La concatenación RGB se utiliza con efectos RGB.
* La concatenación HSL se utiliza con efectos HSL.
* Los recursos que comparten un destino de CGRAM comparten sus colores. Para mostrar dos efectos locales distintos, necesitan destinos que permitan mantener ambos resultados.

=== Si no se acepta la transferencia ===

* Calcular el efecto no significa que ya esté en CGRAM.
* Si la transferencia no se acepta, el administrador puede volver a intentar la actualización.
* Cuando corresponde, se mantiene el resultado anterior utilizable hasta poder sustituirlo.
* No se deben cargar primero los colores originales sin efecto: podrían verse así durante un frame antes del resultado correcto.

== Cómo trabajan juntos ==

El recorrido de un sprite dinámico reúne estas tareas:

# Su lógica elige la pose y la versión de paleta.
# La asignación busca una paleta utilizable y prepara los colores si hace falta.
# La caché protege la pose ya cargada o prepara la carga de una nueva.
# El dibujo escribe los datos de sus piezas en los buffers OAM.
# El administrador de efectos prepara los cambios globales pendientes.
# NMI realiza las transferencias de gráficos y colores solicitadas.

Compartir gráficos, compartir una paleta y compartir una rutina de dibujo son tres cosas distintas. Dynamic Xtreme puede aprovechar cada una sin obligar a que los recursos compartan también las demás.

== Lecturas relacionadas ==

* [[es/Dynamic_Xtreme|Artículo principal]]: funcionalidades y compatibilidad.
* [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos]].
* [[es/Dynamic_Xtreme_sprite_creation_guide|Creación de sprites dinámicos]].
* [[es/Dynamic_Xtreme_UberASM_guide|Dynamic Xtreme con UberASM]].
* [[es/Dynamic_Xtreme_ASM_API|API ASM]].

es/Dynamic Xtreme internal workings

2026-10-25T02:49:13Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_internal_workings}}

En este artículo se explica cómo funciona Dynamic Xtreme, desde la preparación de los recursos al instalarlo hasta la carga y el dibujo de una pose durante el juego.

== Qué prepara la instalación ==

Antes de que un sprite pueda usar sus gráficos o una paleta, Dynamic Xtreme tiene que guardarlos en la ROM y preparar la información para encontrarlos. Lo mismo ocurre con cualquier otro recurso dinámico que hayas añadido.

Para hacerlo, la herramienta lee los DynamicInfo, DrawInfo y PaletteEffect. Cada archivo aporta una parte distinta: qué recursos se van a cargar, cómo se dibujan las poses y qué cambios de color se pueden aplicar.

Gracias a esta preparación se generan defines en <code>DXDefines.asm</code> que permiten utilizar los recursos y ejecutar fácilmente las rutinas necesarias.

=== DynamicInfo: recursos y datos de carga ===

Un DynamicInfo reúne los gráficos de poses, las paletas y los recursos generales que necesita un sprite u otro código. Si incluye gráficos de poses dinámicas, la herramienta los organiza para que puedan cargarse con la distribución de tiles que espera el sistema.

Por cada pose guarda varios datos en tablas separadas. Todas mantienen el mismo orden: la entrada de una pose en una tabla corresponde a esa misma pose en las demás. En la tabla siguiente, '''N''' es la cantidad de poses dinámicas instaladas.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>PoseSize</code> || 2 × N || 2 || La cantidad de datos que utiliza cada pose, en bytes. Se utiliza para comprobar si su carga cabe en el presupuesto del frame.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Cuántos bloques de 16×16 hay que reservar en VRAM para la pose. No siempre coincide exactamente con los bytes que se copian, porque una pieza incompleta también puede necesitar un bloque de espacio.
|-
| <code>PoseResource</code> || 3 × N || 3 || La dirección de los gráficos de cada pose en ROM. Incluye el banco, de modo que el código de carga pueda encontrar su origen completo.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; dos valores por pose || Dos tamaños por pose, correspondientes a los dos tramos en que pueden dividirse sus gráficos. La rutina de carga utiliza esos tamaños para repartirlos correctamente en VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || El desplazamiento en VRAM desde el comienzo del primer tramo hasta el comienzo del segundo. Permite colocar el segundo tramo donde corresponde, aunque el primero termine con una fila incompleta.
|}

Estas tablas describen todas las poses instaladas, no solo las que están en pantalla. Más adelante, la caché guarda por separado cuáles están cargadas y dónde quedaron.

Por ejemplo, si se solicita una pose que todavía no está en VRAM, el sistema consulta cuántos bytes necesita cargar, busca espacio para sus bloques y utiliza la dirección y los datos de sus tramos para preparar la carga.

==== Tablas de paletas ====

Las paletas declaradas en los DynamicInfo se reúnen en <code>PaletteTable</code>. Si '''P''' es la cantidad de entradas de las listas de paletas de los DynamicInfo:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID de cada paleta.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || Dirección de sus colores en ROM.
|}

P cuenta las entradas de las listas, no solo las paletas distintas: una paleta compartida puede aparecer en más de un DynamicInfo.

Las dos listas siguen el orden de las paletas de los DynamicInfo. El define de offset de cada DynamicInfo indica dónde comienza su lista dentro de ellas. Al elegir una versión, el sistema suma ese índice al offset y obtiene tanto el ID como la dirección de los colores elegidos.

El ID permite reconocer y compartir una paleta; la dirección permite cargarla. No son el número de paleta de pantalla: una misma paleta instalada puede terminar, por ejemplo, en la paleta 9 o en la C según la asignación.

==== Recursos generales y defines ====

Los archivos declarados en <code>Resources</code> se guardan en ROM. Su dirección y la cantidad de bytes que ocupan pueden consultarse mediante los defines generados en <code>DXDefines.asm</code>. Por ejemplo, para <code>my_resource.bin</code> se generan:

* <code>!ResourceMyResource</code>: dirección del recurso en ROM.
* <code>!ResourceMyResourceSize</code>: cantidad de bytes que ocupa.
* <code>!ResourceIDMyResource</code>: ID del recurso.

El nombre se normaliza en PascalCase: se eliminan espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra.

=== DrawInfo: datos y rutinas de dibujo ===

El DrawInfo describe cómo está formada una pose: qué tiles tiene, dónde se coloca cada uno, qué tamaño utiliza y cómo cambia al voltearse.

Al instalarlo, Dynamic Xtreme genera rutinas de dibujo optimizadas según los parámetros que utilizan los tiles. Tiene en cuenta, por ejemplo, si necesitan desplazamientos X e Y, si comparten el mismo tamaño, si utilizan propiedades comunes y si requieren volteos.

De esta forma, la rutina realiza el trabajo que necesita ese dibujo sin añadir el manejo de opciones que no utiliza. Varias poses pueden compartirla si necesitan el mismo tratamiento; eso no significa que compartan también sus gráficos o su ID.

La relación entre una pose y su dibujo se guarda en estas tablas. '''D''' es la cantidad de poses de dibujo y '''R''' la cantidad de rutinas generadas:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>TableOffset</code> || 2 × D || 2 || Dónde comienzan los datos de la pose dentro de las tablas de su rutina de dibujo. Así se localizan sus tiles y desplazamientos sin recorrer las poses anteriores.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || La cantidad de tiles de la pose menos uno. Una pose de cuatro tiles guarda 3; la rutina utiliza ese valor para recorrer sus piezas.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Qué rutina de dibujo utiliza cada pose. Las poses con características compatibles pueden apuntar al mismo ID de rutina.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 por rutina || Las direcciones de las rutinas de dibujo. El ID de rutina permite encontrar aquí el código que debe ejecutarse.
|}

Cada rutina tiene, además, las tablas que necesitan sus poses. Aquí '''T''' es la cantidad de entradas de cada tabla de la rutina:

{| class="wikitable"
! Datos !! Bytes totales !! Bytes por valor !! Qué describen
|-
| <code>Tiles</code> || T, si se genera || 1 || Los números de tile que forman la pose.
|-
| <code>Properties</code> || T, si se genera || 1 || Las propiedades de cada pieza, como los volteos y su prioridad respecto a las capas.
|-
| <code>XDisplacements</code> y <code>YDisplacements</code> || T por tabla, si se genera || 1 || La posición de cada tile respecto al punto de origen de la pose.
|-
| Tablas de desplazamientos para los volteos || T por tabla, si se genera || 1 || Las posiciones que deben utilizarse al voltear la pose cuando necesita una distribución distinta.
|-
| <code>Sizes</code> || T, si se genera || 1 || El tamaño de cada tile: 8×8 o 16×16.
|}

No todas estas tablas tienen que aparecer en todas las rutinas. Si un dato es igual para todas las piezas o puede obtenerse de un valor común, la herramienta puede generar una rutina que lo utilice directamente.

La optimización se hace durante la instalación. Si todos los tiles tienen el mismo tamaño, por ejemplo, la rutina puede utilizar ese valor común sin leer un tamaño distinto para cada pieza.

=== PaletteEffect: datos de los efectos ===

Un archivo PaletteEffect contiene una lista de cambios de color. La instalación les asigna IDs y guarda sus datos en <code>PaletteEffectsTable</code>.

Como en las tablas de poses, los datos de cada efecto mantienen la misma posición en las distintas listas. Los IDs de efectos comienzan en 1; el ID 0 se utiliza para indicar que no hay efecto global. En la tabla, '''E''' es la cantidad de efectos instalados; el conjunto ocupa '''2 + 7 × E bytes'''.

{| class="wikitable"
! Parte de la tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>Length</code> || 2 || 2 || La cantidad de efectos instalados.
|-
| <code>Types</code> || E || 1 || El tipo de cada efecto, por ejemplo <code>MixH</code>, <code>MixS</code> o <code>PalTransitionRGB</code>. Indica qué cálculo debe realizarse.
|-
| <code>Value1</code>, <code>Value2</code> y <code>Value3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Los valores de los canales que utiliza el efecto. En una transición, estos tres bytes guardan la dirección de la paleta de destino, no valores de canales.
|-
| <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Cuánto se aplica el cambio en cada componente. Van de 0 a 127.
|}

Si el efecto es una transición hacia otra paleta, la herramienta también prepara esa paleta. Convierte sus colores al formato RGB o HSL que necesita la transición y los guarda en ROM. Durante el juego se puede utilizar ese destino sin tener que convertirlo de nuevo en cada llamada.

Estas paletas de transición son distintas de las paletas normales que se cargan a CGRAM: contienen tres componentes por color y se utilizan para calcular el efecto.

=== Cómo encuentra el código los recursos instalados ===

<code>DXDefines.asm</code> publica los IDs, direcciones, tamaños y offsets que necesitan los recursos. Por ejemplo, <code>!DynamicPoseIDMySpriteIdle</code> identifica una pose y <code>!PaletteEffectIDMyEffect0</code> identifica el primer efecto de un archivo.

Los nombres se normalizan en PascalCase: se eliminan separadores como espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra. <code>my_sprite</code>, por ejemplo, pasa a <code>MySprite</code>.

También se genera <code>BufferTable</code>, que guarda las direcciones de los bloques donde se insertaron los recursos. Cada dirección ocupa 3 bytes y se añade un valor final <code>$FFFFFF</code> de otros 3 bytes. Para B bloques, ocupa <code>3 × (B + 1)</code> bytes. La herramienta utiliza esa información para localizar los datos de una instalación anterior al reinstalar.

Una reinstalación puede cambiar IDs y direcciones. Por eso hay que volver a insertar los sprites, bloques y códigos UberASM que utilizan los defines generados.

== El trabajo de cada frame ==

En la lógica principal se ejecutan el jugador, los sprites y los demás códigos del modo de juego. Los que utilizan Dynamic Xtreme solicitan las poses y paletas que necesitan, preparan los efectos locales y llaman a las rutinas de dibujo. Las cargas que se aceptan quedan anotadas para transferir sus datos durante NMI.

Al terminar esa lógica, el código de game mode de Dynamic Xtreme realiza las tareas que correspondan a las opciones habilitadas: prepara las actualizaciones de VRAM de la optimización de Kevin, mantiene el estado de las paletas y calcula los efectos globales pendientes.

Después, durante NMI, se ejecutan las transferencias preparadas: los gráficos se copian a VRAM y los colores a CGRAM. También se reinicia el contador de datos y se actualizan los relojes del sistema para el siguiente ciclo de trabajo.

El orden que seguiremos para explicarlo es, por tanto, '''lógica principal → tareas al terminar el game mode → transferencias durante NMI'''.

=== Lógica principal ===

Cada recurso decide qué necesita. Un sprite puede cambiar de pose, una animación puede pedir nuevos gráficos y un código UberASM puede cargar una paleta o seleccionar un efecto.

Si la pose solicitada ya está cargada, Dynamic Xtreme actualiza su tiempo de último uso para protegerla del reemplazo y no vuelve a cargar sus gráficos. Si no está cargada, comprueba el presupuesto de datos del frame y busca espacio disponible en VRAM antes de preparar su carga.

El dibujo también se prepara en esta parte: las rutinas escriben en los buffers OAM la posición, los tiles y las propiedades de las piezas que se mostrarán.

Una solicitud puede rechazarse, por ejemplo si no queda presupuesto para sus datos. El recurso que la pidió debe comprobar el resultado y decidir si conserva lo anterior o vuelve a intentarlo después. Una carga rechazada no queda guardada automáticamente para otro frame.

=== Tareas de game mode ===

En esta parte se realizan las siguientes tareas, según las funcionalidades habilitadas.

'''Antes de ejecutar la lógica del juego:'''

# Si está habilitado <code>ControllerOptimization</code>, se ejecuta la rutina del control aquí en lugar de hacerlo en NMI.
# Se comprueba si Dynamic Xtreme debe funcionar en el game mode actual. Si no debe hacerlo, se reinician sus variables. Esto ocurre cada frame que se permanezca en un modo no permitido.

Después se ejecuta la lógica normal del juego, incluidos los sprites y los códigos que solicitan cargas o cambios de paleta.

'''Cuando termina esa lógica:'''

# Si está habilitada la optimización de VRAM de Kevin, se ajustan los destinos de las actualizaciones de Lunar Magic antes de que se transfieran.
# Se ponen en 0 los indicadores de actualización de las paletas y se resta 1 a sus temporizadores de protección si todavía son mayores que 0. Esta parte se omite durante la pausa y en los modos no permitidos.
# Se aplican los efectos globales a las paletas que necesitan actualizarse y se preparan las transferencias de sus colores. Esta parte también se omite si la comprobación anterior impide continuar.

Las copias a VRAM y CGRAM se realizan después, durante NMI. Aquí se deja preparado lo que se va a copiar.

=== Transferencias durante NMI ===

NMI es una interrupción que SNES puede generar al comenzar VBlank, después de dibujar la parte visible de la pantalla. El juego aprovecha ese intervalo para actualizar gráficos, colores y otros datos de video.

En los modos permitidos, la rutina de Dynamic Xtreme reinicia <code>DX_Dynamic_CurrentDataSend</code> y actualiza sus relojes. Después ejecuta las transferencias de gráficos pendientes y luego las de paletas. Si corresponde, también actualiza el color 0,0 preparado por el sistema de efectos.

Para realizar las copias se utiliza DMA. NMI lee cada carga de las listas, configura desde dónde se copiarán los datos, cuántos bytes se copiarán y dónde se colocarán, y ejecuta la transferencia.

El tiempo de VBlank es limitado y SMW también lo necesita para sus actualizaciones de pantalla. Para limitar la cantidad de datos enviados en un frame y evitar flickering, Dynamic Xtreme utiliza <code>DX_Dynamic_CurrentDataSend</code>, que cuenta los bytes de las cargas solicitadas, y <code>DX_Dynamic_MaxDataPerFrame</code>, que establece el límite permitido. Antes de aceptar una carga normal, se comprueba que sus bytes no hagan superar ese límite.

==== Las listas de transferencias ====

Cada transferencia guarda el origen de los datos, su banco, la cantidad de bytes y el destino en VRAM o CGRAM.

Al realizar las copias, NMI recorre las listas desde la última entrada hacia la primera y después las vacía. Esto no borra los gráficos o colores cargados: permanecen en su destino hasta que otro código los cambie.

La lista de VRAM utiliza 0 cuando no tiene entradas. La de CGRAM utiliza <code>$FF</code>, porque guarda el índice de la última entrada en lugar de guardar directamente su cantidad.

Si dos códigos escriben sobre el mismo destino, deben coordinar sus cargas. El orden de las solicitudes no debe utilizarse como sustituto de decidir qué recurso puede ocupar cada espacio.

Normalmente, el recurso se lee desde ROM. Si el recurso se encuentra en un buffer en RAM, el usuario debe conservar su contenido hasta que NMI realice la transferencia. Por ejemplo, si prepara una paleta en RAM, no debe modificar ni reutilizar ese buffer antes de que se copie. La lista guarda su dirección, no una copia de sus datos; Dynamic Xtreme no protege el buffer contra cambios realizados por otros códigos.

==== Presupuesto de datos ====

Las macros de transferencia, como <code>%TransferToVRAM()</code> y <code>%TransferToCGRAM()</code>, comprueban cuántos bytes se han solicitado mediante <code>DX_Dynamic_CurrentDataSend</code>. Si al añadir la nueva carga se supera <code>DX_Dynamic_MaxDataPerFrame</code>, la rechazan. Si la aceptan, suman sus bytes al contador.

El límite predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Su objetivo es evitar flickering por enviar demasiados datos en un mismo frame. Es un límite de cantidad de datos, no una medida exacta del tiempo que tarda cada transferencia.

Estas macros tienen variantes como <code>%ForcedTransferToVRAM()</code> y <code>%ForcedTransferToCGRAM()</code>, que aceptan la carga sin comprobar si supera el límite. Sus bytes también se suman a <code>DX_Dynamic_CurrentDataSend</code>, por lo que reducen lo que queda disponible para las siguientes cargas normales. Se utilizan para cargas prioritarias, como las del jugador; usarlas no evita el flickering si se solicita una cantidad excesiva de datos.

==== Los dos relojes ====

'''DX_Timer: protección de las solicitudes'''

<code>DX_Timer</code> avanza cuando se ejecuta la parte de NMI de Dynamic Xtreme. Además de medir cuánto lleva una pose sin utilizarse, sirve para evitar que un recurso repita sus solicitudes antes de que se procesen las anteriores.

No siempre hay un ciclo de lógica por cada ejecución completa de NMI. Durante slowdown, SMW puede ejecutar una versión reducida de NMI, y puede haber dos ciclos de lógica sin que entre ellos se hayan procesado las listas de transferencias de Dynamic Xtreme.

Sin una protección, un recurso podría añadir otra vez sus cargas a esas listas. Las solicitudes repetidas ocuparían más espacio y podrían provocar flickering.

Para evitarlo, las rutinas con esta protección comparan <code>DX_Timer</code> con un valor guardado por el recurso, normalmente llamado <code>SafeFrame</code>. Si coinciden, el recurso ya hizo su intento con ese valor del reloj y no debe añadir de nuevo las cargas. Si son distintos, guarda el valor actual y puede realizar la nueva solicitud.

<code>DX_Timer</code> continúa avanzando durante la pausa cuando se ejecuta esa parte de NMI.

'''DX_SyncTimer: animaciones sincronizadas'''

La función principal de <code>DX_SyncTimer</code> es dar a los sprites un reloj común para sus animaciones. Por ejemplo, varios sprites que utilizan las mismas poses pueden calcular con este reloj qué pose les corresponde cada cuatro frames.

Así todos cambian al mismo tiempo y solicitan la misma pose. La primera solicitud puede necesitar cargarla; las demás la reutilizan sin programar otra carga de sus gráficos. Esto ahorra transferencias DMA y datos enviados por frame.

Si cada sprite llevara un reloj independiente, podrían terminar usando poses distintas de la misma animación al mismo tiempo y necesitar más cargas y espacio de VRAM.

<code>DX_SyncTimer</code> se detiene durante la pausa y cuando se congela la acción, para que las animaciones sincronizadas también se detengan.

== Carga de gráficos: GraphicsChange ==

<code>GraphicsChange</code> guarda en RAM una lista de solicitudes de carga. Durante NMI se recorren esas solicitudes y se copian sus datos a VRAM.

=== Variables de la lista ===

En esta tabla, '''V''' es el valor de <code>!VRAMTransferSize</code>: 64 por defecto. Las cuatro tablas de solicitudes reservan V bytes cada una; con entradas de 2 bytes, ese valor deja espacio para 32 solicitudes. Junto con el contador, reservan <code>1 + 4 × V</code> bytes: 257 por defecto.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Cantidad de solicitudes pendientes. El valor 0 indica que la lista está vacía.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 por defecto || 2 || Dirección de origen de cada solicitud, sin el banco.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 por defecto || 2 reservados; banco de 1 byte || Banco del origen.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 por defecto || 2 || Cantidad de bytes que se copiarán.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 por defecto || 2 || Dirección de destino en VRAM.
|}

Las tablas mantienen el mismo orden: la primera entrada de cada tabla pertenece a la primera solicitud, la segunda a la segunda, etc. Cada entrada de estas tablas ocupa 2 bytes, por lo que se avanza con desplazamientos de <code>$00</code>, <code>$02</code>, <code>$04</code>, etc.

Estos nombres representan direcciones de RAM calculadas en <code>DXDefines.asm</code>. Sus direcciones pueden cambiar según la configuración y las funcionalidades habilitadas.

=== Añadir una solicitud ===

La macro <code>%TransferToVRAM()</code> realiza los siguientes pasos:

# Calcula cuántos bytes habría en total al añadir la nueva carga a <code>DX_Dynamic_CurrentDataSend</code>.
# Compara el resultado con <code>DX_Dynamic_MaxDataPerFrame</code>. Si lo supera, devuelve el carry desactivado y no añade la solicitud.
# Utiliza <code>DX_PPU_VRAM_Transfer_Length</code> para encontrar la siguiente entrada y aumenta ese contador en 1.
# Guarda el origen, banco, cantidad de bytes y destino en las tablas.
# Actualiza <code>DX_Dynamic_CurrentDataSend</code> con los bytes de la carga y devuelve el carry activado.

<code>%ForcedTransferToVRAM()</code> guarda los mismos datos, pero no comprueba el límite de bytes. Las variantes <code>FromAddr</code> y <code>Resource</code> facilitan obtener el origen desde una dirección completa o desde los defines de un recurso.

Añadir una solicitud no copia los gráficos inmediatamente: deja la información preparada para NMI.

=== Ejecutar las solicitudes durante NMI ===

La rutina <code>VRAMDMA</code>:

# Lee <code>DX_PPU_VRAM_Transfer_Length</code>. Si es 0, termina porque no hay solicitudes.
# Calcula el desplazamiento de la última entrada: <code>(Length - 1) × 2</code>.
# Lee su origen, banco y cantidad de bytes, y los coloca en los registros de DMA.
# Escribe el destino de VRAM en <code>$2116-$2117</code> e inicia la transferencia mediante <code>$420B</code>.
# Retrocede 2 bytes para procesar la solicitud anterior. Repite hasta completar la primera.
# Escribe 0 en <code>DX_PPU_VRAM_Transfer_Length</code> para indicar que la lista está vacía.

'''La lista se ejecuta del final al inicio.''' No hace falta borrar todos sus datos al terminar: al quedar su largo en 0, la próxima solicitud volverá a utilizar la primera entrada.

=== Animaciones con un destino fijo ===

El código de una animación debe:

# Elegir la imagen que corresponde al paso actual.
# Calcular su dirección de origen.
# Solicitar la copia al destino de VRAM de la animación.
# Comprobar el carry. Si se rechaza la carga, conservar la imagen anterior y volver a intentarlo.

El destino puede ser siempre el mismo. Lo que cambia es la imagen que se copia allí; la lista de transferencias no decide cuándo debe avanzar la animación.

Puedes ver un código completo en [[es/Dynamic_Xtreme_UberASM_guide#Crear_animaciones_de_gráficos|Crear animaciones de gráficos de la guía de UberASM]].

=== Carga de una pose dinámica ===

La carga de una pose utiliza la caché para no repetir transferencias de gráficos que ya están disponibles:

# Busca el ID en la tabla hash.
# Si ya está registrado, actualiza su tiempo de uso y no añade otra carga.
# Si no está, comprueba la cantidad de bytes y busca un espacio adecuado en el mapa de VRAM.
# Elige qué poses pueden reemplazarse, teniendo en cuenta su tiempo sin uso y el espacio que necesita la nueva.
# Actualiza las tablas de la caché y el mapa.
# <code>DynamicRoutine</code> divide los datos de la pose en las transferencias necesarias.
# NMI ejecuta esas transferencias.

Cada paso se desarrolla en [[#Sprites_dinámicos:_DynamicPoses|Sprites dinámicos: DynamicPoses]], incluyendo la búsqueda por hash, el mapa, la política de reemplazo y la división de la carga en filas.

== Carga y asignación de paletas: PalettesChange ==

El sistema distingue dos valores:

* '''ID de paleta:''' identifica los colores guardados en ROM.
* '''Destino de pantalla:''' indica qué paleta de CGRAM utilizará esos colores.

La asignación automática permite compartir colores entre sprites sin exigir un destino fijo para cada uno.

=== Lista de cargas a CGRAM ===

En esta tabla, '''C''' es <code>!CGRAMTransferSize</code>: 64 por defecto. El conjunto reserva <code>1 + 7 × C</code> bytes, es decir, 449 con ese valor. Aunque <code>SourceBNK</code> reserva 2 × C bytes, el código utiliza un byte de banco por solicitud.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Índice de la última solicitud pendiente. <code>$FF</code> indica una lista vacía; 0 indica que hay una solicitud.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 por defecto || 2 || Dirección de origen, sin el banco.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 reservados por defecto || 1 utilizado por solicitud || Banco del origen.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 por defecto || 2 || Cantidad de bytes que se copiarán. Cada color ocupa 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 por defecto || 1 || Primer color de destino en CGRAM.
|}

Durante NMI, <code>CGRAMDMA</code>:

# Comienza por la última solicitud pendiente.
# Configura DMA con el origen y la cantidad de bytes de esa solicitud.
# Selecciona el primer color mediante <code>$2121</code> y realiza la copia.
# Continúa con las solicitudes anteriores.
# Al terminar, escribe <code>$FF</code> en <code>DX_PPU_CGRAM_Transfer_Length</code>.

Las macros <code>TransferPalette</code> también actualizan las copias de colores y el estado de efectos:

* '''Sin efecto global:''' solicitan la carga y actualizan los buffers de SMW. Así el juego no vuelve a utilizar colores anteriores durante la animación de victoria del goal.
* '''Con efecto global:''' guardan los colores originales y preparan el estado necesario para aplicarles el efecto antes de enviarlos a CGRAM.

=== Asignación automática ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || Guarda el ID asignado a cada destino. <code>$FFFF</code> indica una entrada libre y <code>$FFFE</code> una reservada.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protege cada destino del reemplazo automático mientras está en uso.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; un bit por paleta de sprites || Indica qué paletas de sprites están asignadas con efecto global habilitado. Esta condición también se compara al compartir una asignación.
|}

La búsqueda sigue este orden:

# Reutilizar una asignación con el mismo ID y una condición de efecto compatible.
# Si no existe, utilizar una entrada libre.
# Si no hay entradas libres, reemplazar una que no esté reservada y cuyo temporizador sea 0.
# Si no encuentra ninguna, indicar que la asignación falló.

Mientras el recurso utiliza la paleta, mantiene su temporizador en 2. Llegar a 0 no borra los colores: la asignación puede reutilizarse si otro recurso todavía no la reemplazó.

=== Asignación manual y versión ===

* '''Manual con carga:''' el código elige el destino y solicita sus colores.
* '''Manual sin carga:''' el código elige el destino y utiliza los colores que ya estaban preparados.
* '''Versión:''' selecciona una entrada de la lista de paletas del DynamicInfo. La última versión procesada permite comprobar si esa selección cambió.

Dos recursos que elijan el mismo destino con colores distintos deben coordinarse. Mantener la protección de una paleta no significa volver a cargar sus colores.

== Dibujo de poses: DrawingSystem ==

El dibujo prepara las piezas de una pose en OAM: qué tiles se muestran, dónde se colocan y qué propiedades utilizan. Los datos gráficos deben estar en VRAM.

=== Pasos del dibujo ===

# Busca la rutina y los datos de la pose mediante <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code> y <code>TableOffset</code>.
# Obtiene la cantidad de piezas desde <code>NumberOfTilesMinus1</code>.
# Calcula la posición de cada tile usando la posición del sprite, sus desplazamientos y los volteos que correspondan.
# Comprueba si la pieza puede verse y si queda espacio de OAM.
# Escribe su posición, número de tile, propiedades y tamaño en los buffers OAM.

El número de tile depende del dibujo:

{| class="wikitable"
! Caso !! Cómo se obtiene el tile
|-
| Pose dinámica || Se ajusta al lugar de VRAM donde quedaron cargados sus gráficos.
|-
| Pose estática || Se utiliza su número de tile fijo.
|-
| Pose que utiliza un tile común || El código debe preparar <code>!Tile</code> antes de llamar al dibujo.
|}

=== Prioridad y espacio disponible ===

* En '''LoROM''', el sistema lleva su propio control de entradas OAM disponibles.
* En '''SA-1''', utiliza la integración con MaxTile.
* La '''prioridad de dibujo''' organiza las piezas de sprites. No es la misma propiedad que determina si un tile queda delante o detrás de las capas.
* Los '''límites por línea de pantalla''' de SNES siguen existiendo. Tener una pose cargada no garantiza que puedan verse todas sus piezas.

== Jugador y Yoshi ==

=== PlayerFeatures ===

El jugador original tiene rutinas propias para elegir y cargar las piezas de sus poses. <code>PlayerFeatures</code> permite integrar ese trabajo con las cargas de Dynamic Xtreme y cambiar el origen de sus gráficos y paletas.

Con el formato original, el juego sigue eligiendo las piezas de la pose. La rutina obtiene sus direcciones desde el origen configurado y compara esas direcciones con las anteriores para cargar las que hayan cambiado.

Estas cargas utilizan transferencias forzadas y sus bytes también cuentan para las solicitudes normales posteriores. Así conservan su prioridad sin quedar fuera de la contabilidad del sistema.

La paleta del jugador tiene un tratamiento especial: combina colores y selecciones del propio juego con el origen personalizado. No funciona simplemente como sustituir una paleta completa de un sprite cualquiera.

El soporte para jugadores personalizados permite que otros sistemas administren de otra forma sus poses y dibujo. No convierte automáticamente cualquier spritesheet al formato del jugador original.

=== YoshiFeatures ===

Yoshi también carga sus gráficos por piezas. <code>YoshiFeatures</code> permite cambiar su origen manteniendo la organización que esperan sus rutinas.

El código calcula qué partes necesita y prepara sus cargas a los destinos correspondientes de VRAM. Como las del jugador, estas cargas tienen un tratamiento prioritario.

Esta opción necesita <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad. No permite evitar un conflicto del sistema del jugador habilitando únicamente las funciones de Yoshi.

== Memoria y optimizaciones ==

=== Free7E2000 ===

SMW mantiene en RAM gráficos originales del jugador, Yoshi y ciertas animaciones. En ROMs sin SA-1, esta opción adapta las cargas para leer esos datos desde ROM.

Dynamic Xtreme aprovecha la RAM recuperada para sus variables internas. No es un espacio que quede libre para que cualquier otro código escriba encima.

SA-1 utiliza otras direcciones y desactiva esta opción. Los rangos están en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Espacios de RAM utilizados]].

=== ControllerOptimization ===

Esta opción mueve el procesamiento del control desde NMI a la parte de game mode. El objetivo es dejar más tiempo para las actualizaciones de pantalla, no añadir un frame de retraso ni cambiar los botones que recibe el juego.

=== FixedColorOptimization ===

El color fijo se utiliza en las mezclas de color de la consola. Para actualizarlo, el juego prepara sus componentes y los envía al registro correspondiente.

La optimización reemplaza esa preparación por una secuencia más corta. El color sigue enviándose a la consola, pero necesita menos trabajo durante NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic utiliza listas llamadas stripe images para actualizar partes de los mapas de tiles. Esas listas incluyen tanto los datos como la información sobre sus destinos.

La versión integrada de la optimización de Kevin prepara fuera de NMI parte del ajuste de esos destinos. Así deja menos trabajo de preparación para el momento de la transferencia.

Esta opción sustituye el uso del parche original por separado. Además, no debe desinstalarse después de instalarla; hay que tenerlo en cuenta antes de activarla.

=== StatusBarOptimization ===

La barra de estado original actualiza zonas concretas de VRAM. Esta opción prepara sus transferencias de forma más directa, reduciendo la configuración de DMA que necesita hacer durante NMI.

No añade una barra nueva. Modifica la actualización de la original y, por eso, entra en conflicto con recursos que la reemplazan, modifican o eliminan.

== Sprites dinámicos: DynamicPoses ==

El sistema funciona como una '''caché de poses en VRAM'''. No reserva una copia de los gráficos para cada sprite: guarda la pose y permite que la reutilicen todos los recursos que la necesiten.

* Una pose se carga una sola vez mientras permanezca en la caché.
* Las siguientes solicitudes actualizan su tiempo de último uso, sin añadir otra carga de sus gráficos.
* La pose no se borra cuando un recurso deja de utilizarla. Permanece allí hasta que se necesite su espacio y se elija reemplazarla.
* Si fue reemplazada y vuelve a solicitarse, tendrá que cargarse otra vez.

La elección no depende de cuánto tiempo lleva la pose desde que se cargó, sino de '''cuánto tiempo lleva sin utilizarse''' y de si su espacio sirve para la pose nueva.

=== Tres valores distintos ===

{| class="wikitable"
! Valor !! Qué identifica
|-
| ID de pose || La pose instalada. Tiene 16 bits y permite consultar sus datos en ROM.
|-
| Índice de la tabla hash || La entrada de RAM donde se registró la pose. Va de 0 a 127.
|-
| Bloque de VRAM || ID de una de las 128 posiciones para tiles de 16×16 que caben en el espacio de VRAM de sprites. Se numeran de izquierda a derecha y de arriba abajo, desde 0 hasta 127. Para una pose que ocupa varios bloques, se guarda el ID de su primer bloque.
|}

El índice de la tabla hash y el bloque de VRAM no tienen por qué coincidir. Una entrada de la tabla puede registrar una pose que empieza en cualquier bloque permitido.

=== Tablas de las poses registradas ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Cantidad de poses registradas.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Cantidad de poses registradas para cada hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || ID completo de la pose de cada entrada. <code>$FFFF</code> indica una entrada libre.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Bloque de VRAM donde comienza cada pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || Valor de <code>DX_Timer</code> de su último uso.
|}

Estas tablas ocupan '''769 bytes''' en RAM. Guardan las poses registradas durante el juego; las tablas generadas desde el DynamicInfo describen, en cambio, todas las poses instaladas.

=== Cómo se busca una pose ===

La rutina <code>DynamicPoseHashmap_FindPose</code> utiliza una tabla hash de 128 entradas. El hash permite elegir dónde empezar a buscar:

<pre>
hash = ID de pose AND $007F
</pre>

Dos IDs diferentes pueden tener el mismo hash. Por ejemplo, <code>$0005</code> y <code>$0085</code> producen <code>$05</code>. Por eso el hash no basta para confirmar que la pose está cargada: también se compara el ID completo.

La búsqueda sigue estos pasos:

# Guarda el ID solicitado y calcula su hash.
# Si <code>DX_Dynamic_Pose_Length</code> es 0, no hay poses registradas y la búsqueda termina.
# Consulta <code>DX_Dynamic_Pose_HashSize[hash]</code>. Si es 0, ninguna pose registrada tiene ese hash y también termina.
# Comienza por la entrada cuyo índice coincide con el hash.
# Lee el ID de esa entrada. Si coincide con el solicitado, encontró la pose.
# Si no coincide, continúa con la siguiente entrada de la secuencia de búsqueda.

La secuencia avanza '''15 entradas por intento''' y vuelve al comienzo al superar 127:

<pre>
siguiente índice = (índice actual + 15) AND $7F
</pre>

Con 128 entradas, ese paso permite visitar todas las posiciones antes de repetir una. Para el hash <code>$05</code>, el comienzo de la secuencia es:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

==== El contador de poses de cada hash ====

Cada hash tiene su propio contador en <code>DX_Dynamic_Pose_HashSize</code>. Por ejemplo, si hay dos poses registradas cuyo ID produce el hash <code>$05</code>, la entrada <code>DX_Dynamic_Pose_HashSize+$05</code> contiene 2.

Ese número indica '''cuántas poses con ese hash existen''', no cuántas posiciones hay que recorrer. La búsqueda utiliza una copia temporal del contador:

# Comienza con la cantidad de poses registrada para el hash solicitado.
# Recorre las posiciones de la secuencia hasta encontrar el ID solicitado o haber comprobado esa cantidad de poses con el mismo hash.
# Cada vez que encuentra una pose con ese hash, pero con otro ID, resta 1 al contador temporal.
# Las posiciones libres y las poses de otros hashes no descuentan nada: continúa buscando.
# Si el contador temporal llega a 0 sin encontrar el ID, la pose solicitada no está registrada y la búsqueda termina.

El contador de <code>DX_Dynamic_Pose_HashSize</code> no se modifica durante esta búsqueda. Solo se actualiza al añadir o retirar poses de la caché.

Por ejemplo, se busca <code>$0105</code>, que produce el hash <code>$05</code>, y el contador de ese hash vale 2:

{| class="wikitable"
! Posición visitada !! ID guardado !! Hash del ID !! Poses del hash $05 que faltan por comprobar
|-
| <code>$05</code> || <code>$0005</code> || <code>$05</code> || 1: tiene el mismo hash, pero no es el ID solicitado.
|-
| <code>$14</code> || <code>$0014</code> || <code>$14</code> || 1: es otro hash, así que no se descuenta.
|-
| <code>$23</code> || <code>$0085</code> || <code>$05</code> || 0: ya se comprobaron las dos poses con ese hash. <code>$0105</code> no está registrada.
|}

Lo habitual es que haya una o dos poses por hash. Esto permite resolver la búsqueda con pocas comprobaciones y un coste normalmente cercano a <code>O(1)</code>. No significa que siempre se visiten solo una o dos posiciones: puede haber entradas de otros hashes entre ellas. Con muchas colisiones, el recorrido puede ser más largo.

'''Una entrada libre no termina la búsqueda.''' Puede haber quedado vacía al reemplazar una pose y existir otra del mismo hash más adelante. El contador permite saber cuándo ya se comprobaron todas las poses de ese hash, incluso si hay huecos entre ellas.

==== Cuando encuentra la pose ====

<code>TakeDynamicRequest</code>:

# Obtiene el índice de la entrada encontrada.
# Escribe el valor actual de <code>DX_Timer</code> en <code>DX_Dynamic_Pose_TimeLastUse</code> para esa entrada.
# Devuelve el éxito de la solicitud, sin volver a programar la carga de sus gráficos.

Así todos los recursos que solicitan ese ID utilizan la misma pose y la mantienen protegida. No importa si el recurso es un sprite normal, cluster, extended u otro código que utiliza el sistema.

Esto también evita duplicar una carga dentro del mismo ciclo: cuando la primera solicitud se acepta, la pose ya queda registrada aunque la transferencia física se vaya a realizar durante NMI.

=== Cuando la pose no está registrada ===

<code>TakeDynamicRequest</code> continúa con la preparación de una carga nueva:

# Consulta <code>PoseSize</code> y calcula <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# Si supera <code>DX_Dynamic_MaxDataPerFrame</code>, termina con fallo, sin cambiar las poses existentes.
# Consulta <code>Pose16x16Blocks</code> para saber cuántos bloques necesita.
# Llama a <code>VRAMMap_GetBestSlot</code> para buscar un espacio adecuado.
# Si no existe un espacio utilizable, termina con fallo.
# Retira del mapa y de la tabla hash las poses que ocupen el espacio elegido.
# Busca una entrada libre de la tabla hash y registra la pose nueva.
# Actualiza el mapa de VRAM y el contador de datos del frame.
# Llama a <code>DynamicRoutine</code> para añadir las transferencias.

El presupuesto se comprueba antes de reemplazar poses. Si la nueva carga no cabe en el frame, no se libera espacio para una solicitud que no se puede atender.

==== Añadir y quitar entradas de la tabla hash ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> busca una entrada cuyo ID sea <code>$FFFF</code>, siguiendo la misma secuencia de pasos de 15.
* <code>DynamicPoseHashmap_Add</code> guarda el ID y su tiempo de uso, aumenta <code>DX_Dynamic_Pose_Length</code> y aumenta el contador de su hash.
* <code>DynamicPoseHashmap_Remove</code> escribe <code>$FFFF</code> en el ID retirado y reduce ambos contadores.

Retirar una entrada no borra por sí solo los píxeles de VRAM. Indica que esa pose dejó de estar disponible en la caché; las nuevas transferencias sobrescribirán el espacio elegido.

=== Cómo se representa el mapa de VRAM ===

El mapa tiene '''128 bloques''' de gráficos de 16×16. En 4bpp, un bloque completo equivale a 128 bytes de gráficos. Las poses incompletas pueden copiar menos datos, pero necesitan reservar los bloques que ocupan.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Bloque donde comienza la región. El bit <code>$80</code> indica que está reservada.
|-
| <code>DX_Dynamic_Tile_Size</code>, también llamada <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || Si el bit <code>$80</code> está activo, los otros bits guardan el tamaño de la región libre menos uno. Si está desactivado, guardan el índice de la pose en la tabla hash.
|}

Son '''256 bytes''' adicionales. Junto con las tablas de poses, el administrador utiliza '''1025 bytes''' de RAM, sin contar las listas de DMA ni las scratch de trabajo.

El mapa guarda la información en los extremos de cada región: su primer y su último bloque. No necesita mantener un registro independiente de la pose en cada bloque intermedio.

Por ejemplo, una región libre de 6 bloques, desde <code>$20</code> hasta <code>$25</code>, guarda en ambos extremos:

* <code>Offset = $20</code>: comienzo de la región.
* <code>Size = $85</code>: bit de región libre <code>$80</code> más el tamaño menos uno, <code>$05</code>.

Si la región está ocupada, el tamaño se obtiene consultando el ID de su entrada hash y después <code>Pose16x16Blocks</code>.

Las configuraciones de <code>DynamicPoseSpaceConfig</code> preparan las regiones disponibles y reservadas de SP1-SP4. Una región reservada no puede elegirse para una pose nueva.

=== Recorrido y búsqueda de espacio ===

<code>VRAMMap_GetBestSlot</code> comienza en el bloque <code>$7F</code> y recorre las regiones hacia atrás:

# Lee el comienzo de la región desde <code>DX_Dynamic_Tile_Offset</code>.
# Comprueba si está reservada.
# Obtiene su tamaño y su puntuación de tiempo sin uso.
# Comprueba si sirve para la pose solicitada o si debe considerar también una región contigua.
# Para pasar a la región anterior, utiliza <code>comienzo de la región - 1</code>.

El registro del último bloque permite saltar regiones completas. No se recorren uno por uno todos los bloques que ocupa una pose.

Durante la búsqueda se conservan los datos del espacio que se está evaluando y del mejor encontrado:

{| class="wikitable"
! Datos de trabajo !! Bytes totales !! Bytes por valor !! Para qué se usan
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 por campo || Comienzo, puntuación y cantidad de bloques del candidato actual.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 por campo || Los mismos campos para el mejor candidato encontrado.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Cantidad de bloques que necesita la pose nueva.
|}

Estos nombres son datos temporales en scratch, no reservas adicionales de RAM persistente.

=== Política de reemplazo: tiempo sin uso y espacio suficiente ===

El sistema no elige simplemente la pose que se cargó primero. Utiliza el tiempo transcurrido desde su '''último uso''':

<pre>
tiempo sin uso = DX_Timer - TimeLastUse de la pose
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> obtiene el tamaño y una puntuación para cada región:

{| class="wikitable"
! Caso !! Puntuación y tratamiento
|-
| Región libre || <code>$FF</code>. Se favorece frente a regiones ocupadas.
|-
| Región ocupada || Tiempo sin uso, limitado a <code>$FE</code>.
|-
| Tiempo sin uso de 0 o 1 || No se puede reemplazar: la pose sigue protegida.
|-
| Región reservada || Se descarta, independientemente del tiempo sin uso.
|}

La protección exige '''al menos dos avances de <code>DX_Timer</code> sin utilizar la pose'''. Cada recurso que vuelve a solicitarla actualiza su tiempo de uso y vuelve a protegerla.

==== Por qué no siempre se reemplaza la pose con más tiempo sin uso ====

La pose nueva necesita espacio suficiente y contiguo. Un espacio pequeño no sirve por sí solo, aunque lleve mucho tiempo sin utilizarse.

Por ejemplo, para una pose nueva de 4 bloques:

{| class="wikitable"
! Espacio candidato !! Tiempo sin uso !! ¿Sirve?
|-
| Pose A: 2 bloques, sin espacio contiguo utilizable || 20 || No: solo deja 2 bloques.
|-
| Pose B: 4 bloques || 8 || Sí: puede alojar la pose nueva.
|}

En este caso se puede reemplazar B y conservar A. A lleva más tiempo sin uso, pero su espacio no permite atender la solicitud.

Si dos o más regiones contiguas pueden reemplazarse, el sistema puede considerarlas juntas. Para esa combinación:

* Suma sus cantidades de bloques.
* Utiliza la '''menor puntuación''' de las regiones combinadas, es decir, el menor tiempo sin uso.
* Si una está reservada o protegida, no puede utilizarla para completar el espacio.

Así una pose usada recientemente no puede quedar sobrescrita por combinarla con otra que lleva mucho tiempo sin uso.

==== Elegir entre candidatos válidos ====

# El candidato debe tener al menos la cantidad de bloques solicitada.
# Se prefiere la puntuación más alta: espacio libre o mayor tiempo sin uso.
# Si las puntuaciones son iguales, se prefiere el candidato con menos bloques, siempre que la pose quepa.
# Si puntuación y tamaño también coinciden, se conserva el candidato que ya se había elegido.

Las regiones se combinan durante la búsqueda cuando el candidato todavía es demasiado pequeño. No se juntan todas las regiones reemplazables sin tener en cuenta el tamaño solicitado.

=== Reemplazar y dividir la región elegida ===

Una vez elegido el espacio:

# <code>VRAMMap_RemovePosesInSpace</code> recorre sus regiones y retira de la tabla hash las poses que haya que reemplazar.
# <code>VRAMMap_RemoveSpace</code> representa el espacio elegido como una región libre, actualizando sus extremos.
# Se busca una entrada hash libre y se guarda el bloque de comienzo en <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registra la pose.
# <code>VRAMMap_AddPoseInSpace</code> escribe el índice hash de la pose y el comienzo de su región en el primer y último bloque.
# Si sobran bloques, crea otra región libre con el resto.

Si una región de 6 bloques aloja una pose de 4, quedan una región ocupada de 4 y una libre de 2. No se mueven las demás poses para compactar VRAM.

=== DynamicRoutine: preparar las transferencias de la pose ===

En este punto ya se eligió el espacio y se registró la pose. <code>DynamicRoutine</code> convierte esa asignación en solicitudes de transferencia.

Utiliza estos datos:

{| class="wikitable"
! Dato !! Cantidad consultada por pose !! Para qué sirve
|-
| Bloque de comienzo || 1 byte || Lugar elegido por el mapa de VRAM.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes de una tabla de 256 bytes || Convierte uno de los 128 bloques en un desplazamiento de VRAM.
|-
| <code>PoseResource</code> || 3 bytes || Dirección completa de los datos de la pose en ROM.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: dos valores de 2 || Cantidad de bytes del primer y del segundo tramo.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || Desplazamiento de VRAM para el segundo tramo.
|}

==== Convertir el bloque en una dirección de VRAM ====

Los bloques de 16×16 no se convierten simplemente en un desplazamiento lineal de bytes. Cada uno utiliza tiles de 8×8 distribuidos en las filas de VRAM.

<code>OffsetToVRAMOffset</code> contempla esa distribución. Por ejemplo:

{| class="wikitable"
! Bloque !! Desplazamiento !! Dirección de VRAM
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

Estas direcciones de VRAM están expresadas en palabras de 2 bytes, no en bytes. La rutina suma la base <code>$6000</code> utilizada para los gráficos de sprites.

==== Procesar los tramos y sus filas ====

# Obtiene el origen desde <code>PoseResource</code>.
# Procesa los bytes del primer tramo mediante <code>DynamicRoutineLine</code>.
# Si el segundo tramo tiene tamaño 0, termina.
# Si existe, adelanta el origen la cantidad de bytes del primer tramo.
# Suma <code>PoseSecondLineOffset</code> al desplazamiento de VRAM y procesa el segundo tramo.

<code>DynamicRoutineLine</code> divide cada tramo según las filas y el punto de comienzo. Para un destino V expresado en palabras de VRAM, prepara:

<pre>
Final de la primera fila = (V + $0100) AND $FF00
Bytes hasta ese final = (final de la primera fila - V) × 2
Destino de la segunda parte = final de la primera fila + $0100
Bytes de la segunda parte de un grupo = $0200 - bytes de la primera
</pre>

Los tamaños son cantidades de bytes, mientras que los destinos de VRAM están expresados en palabras. Por eso se multiplica por 2 al calcular cuántos datos caben hasta el final de una fila.

La rutina utiliza tres recorridos:

* <code>.EndLine</code>: añade una solicitud final con los bytes restantes.
* <code>.TwoLinesWithEndLine</code>: añade dos solicitudes para los datos restantes, cada una con su destino y cantidad de bytes.
* <code>.TwoLines</code>: añade dos solicitudes que suman <code>$0200</code> bytes, avanza el origen y los destinos y repite con los datos que faltan.

Hay un caso directo antes del recorrido general: si el destino comienza en un límite de <code>$0100</code> palabras y el tramo tiene al menos <code>$0200</code> bytes, la rutina utiliza <code>.EndLine</code> para preparar la copia del tramo completo en una solicitud.

Por ejemplo, un tramo de <code>$0200</code> bytes que comienza en <code>$6020</code> se divide así:

{| class="wikitable"
! Solicitud !! Origen !! Destino VRAM !! Bytes
|-
| Primera || Comienzo del tramo || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Segunda || Comienzo del tramo + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Las dos solicitudes copian los 512 bytes del tramo, respetando los destinos que calcula la distribución de filas. No son dos copias completas de la pose.

Cada solicitud utiliza estas tablas:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Por cada solicitud añadida aumenta <code>DX_PPU_VRAM_Transfer_Length</code>.

La cantidad total de bytes de la pose ya se comprobó y se añadió a <code>DX_Dynamic_CurrentDataSend</code> en <code>TakeDynamicRequest</code>. Esta parte divide esa carga en transferencias; no vuelve a contar la pose completa por cada solicitud.

<code>DynamicRoutine</code> '''no ejecuta DMA'''. Deja las solicitudes preparadas para que <code>VRAMDMA</code> las copie durante NMI.

=== Qué conserva el sprite ===

Las rutinas de sprites guardan el índice hash de la pose utilizable, no una copia independiente de sus gráficos. Ese índice permite consultar su bloque de VRAM y mantener actualizado su tiempo de uso.

Si una pose nueva no puede cargarse:

* Si existe una pose anterior válida, se mantiene y se actualiza su tiempo de uso para protegerla.
* Si nunca hubo una pose válida, no se debe dibujar como si la solicitud hubiera tenido éxito.
* En las llamadas con soporte para mantener la anterior, el carry puede indicar que todavía hay una pose utilizable aunque no se haya completado el cambio.

La animación y el movimiento siguen siendo responsabilidad del sprite. La caché se ocupa de reutilizar o preparar los gráficos solicitados.

== Efectos de paleta: PalettesEffects ==

El sistema conserva los colores originales para poder cambiar de efecto, combinarlo con otro o volver a la paleta sin efecto. No debe utilizar el resultado ya afectado como si fuera la paleta original.

=== Buffers de colores ===

{| class="wikitable"
! Variable o buffer !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 por color || Colores de base en formato SNES, con 2 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 por color || Base separada en rojo, verde y azul, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 por color || Base separada en tono, saturación y luminosidad, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 por color || Resultado en formato SNES, listo para solicitar su copia a CGRAM. Corresponde al buffer de paletas del juego.
|}

=== Indicadores de cada paleta ===

Cada bit de estos indicadores corresponde a una paleta. Las variables <code>BG</code> cubren 0-7 y las <code>SP</code> cubren 8-F.

{| class="wikitable"
! Variables !! Bytes totales !! Bytes por valor !! Qué indican
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> y <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si ya se preparó la base de colores en formato SNES.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> y <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparado el resultado del efecto global.
|}

Estos indicadores evitan repetir conversiones y cálculos que siguen siendo válidos.

=== Preparar una base ===

# Se comprueba si la paleta ya tiene una base registrada.
# Si no la tiene, se obtienen los colores del buffer del juego. Una carga explícita, como <code>TransferPalette</code>, puede proporcionar esa base directamente.
# Se comprueba si el efecto necesita RGB o HSL.
# Si falta esa conversión, se prepara y se marca como disponible.

Si solo cambia el efecto, la base puede seguir siendo válida. Si cambian los colores originales, las llamadas de carga actualizan la base e invalidan las conversiones y resultados que deben calcularse otra vez.

=== Datos de un efecto ===

El ID permite consultar las tablas generadas durante la instalación:

* <code>Types</code>: cálculo que debe realizarse.
* <code>Value1</code>, <code>Value2</code> y <code>Value3</code>: valores de los canales o dirección de la paleta de destino de una transición.
* <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code>: cuánto se aplica cada cambio.

Los canales utilizan valores de 0 a 31. Los ratios van de 0 a 127: 0 conserva el origen y 127 aplica por completo el cambio elegido.

Los cálculos se realizan fuera de NMI. NMI realiza la transferencia de los colores resultantes.

=== Efecto global ===

{| class="wikitable"
! Variable !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selecciona el efecto global. El valor 0 permite restaurar los colores de base.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 0-7 que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 8-F que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Guarda el último ID global procesado por cada paleta.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controla la participación del color fijo y el color 0,0.
|}

Para cada paleta habilitada, el administrador:

# Comprueba si necesita actualizar el resultado del efecto.
# Prepara la base RGB o HSL si todavía falta.
# Calcula el efecto si el resultado anterior ya no sirve.
# Prepara los colores en formato SNES y solicita su transferencia.
# Confirma el ID procesado cuando la carga correspondiente se acepta.

Si se mantiene el mismo efecto y no cambió la base, no hace falta calcularlo otra vez. Al cambiar el ID global se invalidan los resultados anteriores, no necesariamente las bases RGB y HSL.

El ID global 0 también requiere una actualización: el sistema debe cargar de nuevo los colores de base para quitar el efecto anterior.

=== Efecto local y concatenación ===

Un recurso puede tener un efecto propio y recibir también el global. Por ejemplo, un sprite puede cambiar de tono y después oscurecerse junto con el nivel.

El orden es:

# Preparar el resultado del efecto local.
# Utilizarlo como base para el efecto global mediante la llamada de concatenación.
# Calcular el efecto global sobre esa base.
# Cargar el resultado combinado, sin mostrar antes la versión que solo tiene el efecto local.

* La concatenación RGB se utiliza con efectos RGB.
* La concatenación HSL se utiliza con efectos HSL.
* Los recursos que comparten un destino de CGRAM comparten sus colores. Para mostrar dos efectos locales distintos, necesitan destinos que permitan mantener ambos resultados.

=== Si no se acepta la transferencia ===

* Calcular el efecto no significa que ya esté en CGRAM.
* Si la transferencia no se acepta, el administrador puede volver a intentar la actualización.
* Cuando corresponde, se mantiene el resultado anterior utilizable hasta poder sustituirlo.
* No se deben cargar primero los colores originales sin efecto: podrían verse así durante un frame antes del resultado correcto.

== Cómo trabajan juntos ==

El recorrido de un sprite dinámico reúne estas tareas:

# Su lógica elige la pose y la versión de paleta.
# La asignación busca una paleta utilizable y prepara los colores si hace falta.
# La caché protege la pose ya cargada o prepara la carga de una nueva.
# El dibujo escribe los datos de sus piezas en los buffers OAM.
# El administrador de efectos prepara los cambios globales pendientes.
# NMI realiza las transferencias de gráficos y colores solicitadas.

Compartir gráficos, compartir una paleta y compartir una rutina de dibujo son tres cosas distintas. Dynamic Xtreme puede aprovechar cada una sin obligar a que los recursos compartan también las demás.

== Lecturas relacionadas ==

* [[es/Dynamic_Xtreme|Artículo principal]]: funcionalidades y compatibilidad.
* [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos]].
* [[es/Dynamic_Xtreme_sprite_creation_guide|Creación de sprites dinámicos]].
* [[es/Dynamic_Xtreme_UberASM_guide|Dynamic Xtreme con UberASM]].
* [[es/Dynamic_Xtreme_ASM_API|API ASM]].

es/Dynamic Xtreme internal workings

2026-10-25T02:38:52Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme_internal_workings}}

En este artículo se explica cómo funciona Dynamic Xtreme, desde la preparación de los recursos al instalarlo hasta la carga y el dibujo de una pose durante el juego.

== Qué prepara la instalación ==

Antes de que un sprite pueda usar sus gráficos o una paleta, Dynamic Xtreme tiene que guardarlos en la ROM y preparar la información para encontrarlos. Lo mismo ocurre con cualquier otro recurso dinámico que hayas añadido.

Para hacerlo, la herramienta lee los DynamicInfo, DrawInfo y PaletteEffect. Cada archivo aporta una parte distinta: qué recursos se van a cargar, cómo se dibujan las poses y qué cambios de color se pueden aplicar.

Gracias a esta preparación se generan defines en <code>DXDefines.asm</code> que permiten utilizar los recursos y ejecutar fácilmente las rutinas necesarias.

=== DynamicInfo: recursos y datos de carga ===

Un DynamicInfo reúne los gráficos de poses, las paletas y los recursos generales que necesita un sprite u otro código. Si incluye gráficos de poses dinámicas, la herramienta los organiza para que puedan cargarse con la distribución de tiles que espera el sistema.

Por cada pose guarda varios datos en tablas separadas. Todas mantienen el mismo orden: la entrada de una pose en una tabla corresponde a esa misma pose en las demás. En la tabla siguiente, '''N''' es la cantidad de poses dinámicas instaladas.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>PoseSize</code> || 2 × N || 2 || La cantidad de datos que utiliza cada pose, en bytes. Se utiliza para comprobar si su carga cabe en el presupuesto del frame.
|-
| <code>Pose16x16Blocks</code> || N || 1 || Cuántos bloques de 16×16 hay que reservar en VRAM para la pose. No siempre coincide exactamente con los bytes que se copian, porque una pieza incompleta también puede necesitar un bloque de espacio.
|-
| <code>PoseResource</code> || 3 × N || 3 || La dirección de los gráficos de cada pose en ROM. Incluye el banco, de modo que el código de carga pueda encontrar su origen completo.
|-
| <code>PoseResourceSizePerLine</code> || 4 × N || 2; dos valores por pose || Dos tamaños por pose, correspondientes a los dos tramos en que pueden dividirse sus gráficos. La rutina de carga utiliza esos tamaños para repartirlos correctamente en VRAM.
|-
| <code>PoseSecondLineOffset</code> || 2 × N || 2 || El desplazamiento en VRAM desde el comienzo del primer tramo hasta el comienzo del segundo. Permite colocar el segundo tramo donde corresponde, aunque el primero termine con una fila incompleta.
|}

Estas tablas describen todas las poses instaladas, no solo las que están en pantalla. Más adelante, la caché guarda por separado cuáles están cargadas y dónde quedaron.

Por ejemplo, si se solicita una pose que todavía no está en VRAM, el sistema consulta cuántos bytes necesita cargar, busca espacio para sus bloques y utiliza la dirección y los datos de sus tramos para preparar la carga.

==== Tablas de paletas ====

Las paletas declaradas en los DynamicInfo se reúnen en <code>PaletteTable</code>. Si '''P''' es la cantidad de entradas de las listas de paletas de los DynamicInfo:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>PaletteTable.IDs</code> || 2 × P || 2 || ID de cada paleta.
|-
| <code>PaletteTable.Addresses</code> || 3 × P || 3 || Dirección de sus colores en ROM.
|}

P cuenta las entradas de las listas, no solo las paletas distintas: una paleta compartida puede aparecer en más de un DynamicInfo.

Las dos listas siguen el orden de las paletas de los DynamicInfo. El define de offset de cada DynamicInfo indica dónde comienza su lista dentro de ellas. Al elegir una versión, el sistema suma ese índice al offset y obtiene tanto el ID como la dirección de los colores elegidos.

El ID permite reconocer y compartir una paleta; la dirección permite cargarla. No son el número de paleta de pantalla: una misma paleta instalada puede terminar, por ejemplo, en la paleta 9 o en la C según la asignación.

==== Recursos generales y defines ====

Los archivos declarados en <code>Resources</code> se guardan en ROM. Su dirección y la cantidad de bytes que ocupan pueden consultarse mediante los defines generados en <code>DXDefines.asm</code>. Por ejemplo, para <code>my_resource.bin</code> se generan:

* <code>!ResourceMyResource</code>: dirección del recurso en ROM.
* <code>!ResourceMyResourceSize</code>: cantidad de bytes que ocupa.
* <code>!ResourceIDMyResource</code>: ID del recurso.

El nombre se normaliza en PascalCase: se eliminan espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra.

=== DrawInfo: datos y rutinas de dibujo ===

El DrawInfo describe cómo está formada una pose: qué tiles tiene, dónde se coloca cada uno, qué tamaño utiliza y cómo cambia al voltearse.

Al instalarlo, Dynamic Xtreme genera rutinas de dibujo optimizadas según los parámetros que utilizan los tiles. Tiene en cuenta, por ejemplo, si necesitan desplazamientos X e Y, si comparten el mismo tamaño, si utilizan propiedades comunes y si requieren volteos.

De esta forma, la rutina realiza el trabajo que necesita ese dibujo sin añadir el manejo de opciones que no utiliza. Varias poses pueden compartirla si necesitan el mismo tratamiento; eso no significa que compartan también sus gráficos o su ID.

La relación entre una pose y su dibujo se guarda en estas tablas. '''D''' es la cantidad de poses de dibujo y '''R''' la cantidad de rutinas generadas:

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Qué guarda y para qué sirve
|-
| <code>TableOffset</code> || 2 × D || 2 || Dónde comienzan los datos de la pose dentro de las tablas de su rutina de dibujo. Así se localizan sus tiles y desplazamientos sin recorrer las poses anteriores.
|-
| <code>NumberOfTilesMinus1</code> || D || 1 || La cantidad de tiles de la pose menos uno. Una pose de cuatro tiles guarda 3; la rutina utiliza ese valor para recorrer sus piezas.
|-
| <code>GraphicRoutineIDs</code> || D || 1 || Qué rutina de dibujo utiliza cada pose. Las poses con características compatibles pueden apuntar al mismo ID de rutina.
|-
| <code>GraphicRoutine</code> || 3 × R || 3 por rutina || Las direcciones de las rutinas de dibujo. El ID de rutina permite encontrar aquí el código que debe ejecutarse.
|}

Cada rutina tiene, además, las tablas que necesitan sus poses. Aquí '''T''' es la cantidad de entradas de cada tabla de la rutina:

{| class="wikitable"
! Datos !! Bytes totales !! Bytes por valor !! Qué describen
|-
| <code>Tiles</code> || T, si se genera || 1 || Los números de tile que forman la pose.
|-
| <code>Properties</code> || T, si se genera || 1 || Las propiedades de cada pieza, como los volteos y su prioridad respecto a las capas.
|-
| <code>XDisplacements</code> y <code>YDisplacements</code> || T por tabla, si se genera || 1 || La posición de cada tile respecto al punto de origen de la pose.
|-
| Tablas de desplazamientos para los volteos || T por tabla, si se genera || 1 || Las posiciones que deben utilizarse al voltear la pose cuando necesita una distribución distinta.
|-
| <code>Sizes</code> || T, si se genera || 1 || El tamaño de cada tile: 8×8 o 16×16.
|}

No todas estas tablas tienen que aparecer en todas las rutinas. Si un dato es igual para todas las piezas o puede obtenerse de un valor común, la herramienta puede generar una rutina que lo utilice directamente.

La optimización se hace durante la instalación. Si todos los tiles tienen el mismo tamaño, por ejemplo, la rutina puede utilizar ese valor común sin leer un tamaño distinto para cada pieza.

=== PaletteEffect: datos de los efectos ===

Un archivo PaletteEffect contiene una lista de cambios de color. La instalación les asigna IDs y guarda sus datos en <code>PaletteEffectsTable</code>.

Como en las tablas de poses, los datos de cada efecto mantienen la misma posición en las distintas listas. Los IDs de efectos comienzan en 1; el ID 0 se utiliza para indicar que no hay efecto global. En la tabla, '''E''' es la cantidad de efectos instalados; el conjunto ocupa '''2 + 7 × E bytes'''.

{| class="wikitable"
! Parte de la tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>Length</code> || 2 || 2 || La cantidad de efectos instalados.
|-
| <code>Types</code> || E || 1 || El tipo de cada efecto, por ejemplo <code>MixH</code>, <code>MixS</code> o <code>PalTransitionRGB</code>. Indica qué cálculo debe realizarse.
|-
| <code>Value1</code>, <code>Value2</code> y <code>Value3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Los valores de los canales que utiliza el efecto. En una transición, estos tres bytes guardan la dirección de la paleta de destino, no valores de canales.
|-
| <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code> || E por tabla; 3 × E entre las tres || 1 por tabla || Cuánto se aplica el cambio en cada componente. Van de 0 a 127.
|}

Si el efecto es una transición hacia otra paleta, la herramienta también prepara esa paleta. Convierte sus colores al formato RGB o HSL que necesita la transición y los guarda en ROM. Durante el juego se puede utilizar ese destino sin tener que convertirlo de nuevo en cada llamada.

Estas paletas de transición son distintas de las paletas normales que se cargan a CGRAM: contienen tres componentes por color y se utilizan para calcular el efecto.

=== Cómo encuentra el código los recursos instalados ===

<code>DXDefines.asm</code> publica los IDs, direcciones, tamaños y offsets que necesitan los recursos. Por ejemplo, <code>!DynamicPoseIDMySpriteIdle</code> identifica una pose y <code>!PaletteEffectIDMyEffect0</code> identifica el primer efecto de un archivo.

Los nombres se normalizan en PascalCase: se eliminan separadores como espacios, guiones y guiones bajos, y se pone en mayúscula la inicial de cada palabra. <code>my_sprite</code>, por ejemplo, pasa a <code>MySprite</code>.

También se genera <code>BufferTable</code>, que guarda las direcciones de los bloques donde se insertaron los recursos. Cada dirección ocupa 3 bytes y se añade un valor final <code>$FFFFFF</code> de otros 3 bytes. Para B bloques, ocupa <code>3 × (B + 1)</code> bytes. La herramienta utiliza esa información para localizar los datos de una instalación anterior al reinstalar.

Una reinstalación puede cambiar IDs y direcciones. Por eso hay que volver a insertar los sprites, bloques y códigos UberASM que utilizan los defines generados.

== El trabajo de cada frame ==

En la lógica principal se ejecutan el jugador, los sprites y los demás códigos del modo de juego. Los que utilizan Dynamic Xtreme solicitan las poses y paletas que necesitan, preparan los efectos locales y llaman a las rutinas de dibujo. Las cargas que se aceptan quedan anotadas para transferir sus datos durante NMI.

Al terminar esa lógica, el código de game mode de Dynamic Xtreme realiza las tareas que correspondan a las opciones habilitadas: prepara las actualizaciones de VRAM de la optimización de Kevin, mantiene el estado de las paletas y calcula los efectos globales pendientes.

Después, durante NMI, se ejecutan las transferencias preparadas: los gráficos se copian a VRAM y los colores a CGRAM. También se reinicia el contador de datos y se actualizan los relojes del sistema para el siguiente ciclo de trabajo.

El orden que seguiremos para explicarlo es, por tanto, '''lógica principal → tareas al terminar el game mode → transferencias durante NMI'''.

=== Lógica principal ===

Cada recurso decide qué necesita. Un sprite puede cambiar de pose, una animación puede pedir nuevos gráficos y un código UberASM puede cargar una paleta o seleccionar un efecto.

Si la pose solicitada ya está cargada, Dynamic Xtreme actualiza su tiempo de último uso para protegerla del reemplazo y no vuelve a cargar sus gráficos. Si no está cargada, comprueba el presupuesto de datos del frame y busca espacio disponible en VRAM antes de preparar su carga.

El dibujo también se prepara en esta parte: las rutinas escriben en los buffers OAM la posición, los tiles y las propiedades de las piezas que se mostrarán.

Una solicitud puede rechazarse, por ejemplo si no queda presupuesto para sus datos. El recurso que la pidió debe comprobar el resultado y decidir si conserva lo anterior o vuelve a intentarlo después. Una carga rechazada no queda guardada automáticamente para otro frame.

=== Tareas de game mode ===

En esta parte se realizan las siguientes tareas, según las funcionalidades habilitadas.

'''Antes de ejecutar la lógica del juego:'''

# Si está habilitado <code>ControllerOptimization</code>, se ejecuta la rutina del control aquí en lugar de hacerlo en NMI.
# Se comprueba si Dynamic Xtreme debe funcionar en el game mode actual. Si no debe hacerlo, se reinician sus variables. Esto ocurre cada frame que se permanezca en un modo no permitido.

Después se ejecuta la lógica normal del juego, incluidos los sprites y los códigos que solicitan cargas o cambios de paleta.

'''Cuando termina esa lógica:'''

# Si está habilitada la optimización de VRAM de Kevin, se ajustan los destinos de las actualizaciones de Lunar Magic antes de que se transfieran.
# Se ponen en 0 los indicadores de actualización de las paletas y se resta 1 a sus temporizadores de protección si todavía son mayores que 0. Esta parte se omite durante la pausa y en los modos no permitidos.
# Se aplican los efectos globales a las paletas que necesitan actualizarse y se preparan las transferencias de sus colores. Esta parte también se omite si la comprobación anterior impide continuar.

Las copias a VRAM y CGRAM se realizan después, durante NMI. Aquí se deja preparado lo que se va a copiar.

=== Transferencias durante NMI ===

NMI es una interrupción que SNES puede generar al comenzar VBlank, después de dibujar la parte visible de la pantalla. El juego aprovecha ese intervalo para actualizar gráficos, colores y otros datos de video.

En los modos permitidos, la rutina de Dynamic Xtreme reinicia <code>DX_Dynamic_CurrentDataSend</code> y actualiza sus relojes. Después ejecuta las transferencias de gráficos pendientes y luego las de paletas. Si corresponde, también actualiza el color 0,0 preparado por el sistema de efectos.

Para realizar las copias se utiliza DMA. NMI lee cada carga de las listas, configura desde dónde se copiarán los datos, cuántos bytes se copiarán y dónde se colocarán, y ejecuta la transferencia.

El tiempo de VBlank es limitado y SMW también lo necesita para sus actualizaciones de pantalla. Para limitar la cantidad de datos enviados en un frame y evitar flickering, Dynamic Xtreme utiliza <code>DX_Dynamic_CurrentDataSend</code>, que cuenta los bytes de las cargas solicitadas, y <code>DX_Dynamic_MaxDataPerFrame</code>, que establece el límite permitido. Antes de aceptar una carga normal, se comprueba que sus bytes no hagan superar ese límite.

==== Las listas de transferencias ====

Cada transferencia guarda el origen de los datos, su banco, la cantidad de bytes y el destino en VRAM o CGRAM.

Al realizar las copias, NMI recorre las listas desde la última entrada hacia la primera y después las vacía. Esto no borra los gráficos o colores cargados: permanecen en su destino hasta que otro código los cambie.

La lista de VRAM utiliza 0 cuando no tiene entradas. La de CGRAM utiliza <code>$FF</code>, porque guarda el índice de la última entrada en lugar de guardar directamente su cantidad.

Si dos códigos escriben sobre el mismo destino, deben coordinar sus cargas. El orden de las solicitudes no debe utilizarse como sustituto de decidir qué recurso puede ocupar cada espacio.

Normalmente, el recurso se lee desde ROM. Si el recurso se encuentra en un buffer en RAM, el usuario debe conservar su contenido hasta que NMI realice la transferencia. Por ejemplo, si prepara una paleta en RAM, no debe modificar ni reutilizar ese buffer antes de que se copie. La lista guarda su dirección, no una copia de sus datos; Dynamic Xtreme no protege el buffer contra cambios realizados por otros códigos.

==== Presupuesto de datos ====

Las macros de transferencia, como <code>%TransferToVRAM()</code> y <code>%TransferToCGRAM()</code>, comprueban cuántos bytes se han solicitado mediante <code>DX_Dynamic_CurrentDataSend</code>. Si al añadir la nueva carga se supera <code>DX_Dynamic_MaxDataPerFrame</code>, la rechazan. Si la aceptan, suman sus bytes al contador.

El límite predeterminado es <code>$0800</code>, equivalente a 2048 bytes. Su objetivo es evitar flickering por enviar demasiados datos en un mismo frame. Es un límite de cantidad de datos, no una medida exacta del tiempo que tarda cada transferencia.

Estas macros tienen variantes como <code>%ForcedTransferToVRAM()</code> y <code>%ForcedTransferToCGRAM()</code>, que aceptan la carga sin comprobar si supera el límite. Sus bytes también se suman a <code>DX_Dynamic_CurrentDataSend</code>, por lo que reducen lo que queda disponible para las siguientes cargas normales. Se utilizan para cargas prioritarias, como las del jugador; usarlas no evita el flickering si se solicita una cantidad excesiva de datos.

==== Los dos relojes ====

'''DX_Timer: protección de las solicitudes'''

<code>DX_Timer</code> avanza cuando se ejecuta la parte de NMI de Dynamic Xtreme. Además de medir cuánto lleva una pose sin utilizarse, sirve para evitar que un recurso repita sus solicitudes antes de que se procesen las anteriores.

No siempre hay un ciclo de lógica por cada ejecución completa de NMI. Durante slowdown, SMW puede ejecutar una versión reducida de NMI, y puede haber dos ciclos de lógica sin que entre ellos se hayan procesado las listas de transferencias de Dynamic Xtreme.

Sin una protección, un recurso podría añadir otra vez sus cargas a esas listas. Las solicitudes repetidas ocuparían más espacio y podrían provocar flickering.

Para evitarlo, las rutinas con esta protección comparan <code>DX_Timer</code> con un valor guardado por el recurso, normalmente llamado <code>SafeFrame</code>. Si coinciden, el recurso ya hizo su intento con ese valor del reloj y no debe añadir de nuevo las cargas. Si son distintos, guarda el valor actual y puede realizar la nueva solicitud.

<code>DX_Timer</code> continúa avanzando durante la pausa cuando se ejecuta esa parte de NMI.

'''DX_SyncTimer: animaciones sincronizadas'''

La función principal de <code>DX_SyncTimer</code> es dar a los sprites un reloj común para sus animaciones. Por ejemplo, varios sprites que utilizan las mismas poses pueden calcular con este reloj qué pose les corresponde cada cuatro frames.

Así todos cambian al mismo tiempo y solicitan la misma pose. La primera solicitud puede necesitar cargarla; las demás la reutilizan sin programar otra carga de sus gráficos. Esto ahorra transferencias DMA y datos enviados por frame.

Si cada sprite llevara un reloj independiente, podrían terminar usando poses distintas de la misma animación al mismo tiempo y necesitar más cargas y espacio de VRAM.

<code>DX_SyncTimer</code> se detiene durante la pausa y cuando se congela la acción, para que las animaciones sincronizadas también se detengan.

== Carga de gráficos: GraphicsChange ==

<code>GraphicsChange</code> guarda en RAM una lista de solicitudes de carga. Durante NMI se recorren esas solicitudes y se copian sus datos a VRAM.

=== Variables de la lista ===

En esta tabla, '''V''' es el valor de <code>!VRAMTransferSize</code>: 64 por defecto. Las cuatro tablas de solicitudes reservan V bytes cada una; con entradas de 2 bytes, ese valor deja espacio para 32 solicitudes. Junto con el contador, reservan <code>1 + 4 × V</code> bytes: 257 por defecto.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_VRAM_Transfer_Length</code> || 1 || 1 || Cantidad de solicitudes pendientes. El valor 0 indica que la lista está vacía.
|-
| <code>DX_PPU_VRAM_Transfer_Source</code> || V; 64 por defecto || 2 || Dirección de origen de cada solicitud, sin el banco.
|-
| <code>DX_PPU_VRAM_Transfer_SourceBNK</code> || V; 64 por defecto || 2 reservados; banco de 1 byte || Banco del origen.
|-
| <code>DX_PPU_VRAM_Transfer_SourceLength</code> || V; 64 por defecto || 2 || Cantidad de bytes que se copiarán.
|-
| <code>DX_PPU_VRAM_Transfer_Offset</code> || V; 64 por defecto || 2 || Dirección de destino en VRAM.
|}

Las tablas mantienen el mismo orden: la primera entrada de cada tabla pertenece a la primera solicitud, la segunda a la segunda, etc. Cada entrada de estas tablas ocupa 2 bytes, por lo que se avanza con desplazamientos de <code>$00</code>, <code>$02</code>, <code>$04</code>, etc.

Estos nombres representan direcciones de RAM calculadas en <code>DXDefines.asm</code>. Sus direcciones pueden cambiar según la configuración y las funcionalidades habilitadas.

=== Añadir una solicitud ===

La macro <code>%TransferToVRAM()</code> realiza los siguientes pasos:

# Calcula cuántos bytes habría en total al añadir la nueva carga a <code>DX_Dynamic_CurrentDataSend</code>.
# Compara el resultado con <code>DX_Dynamic_MaxDataPerFrame</code>. Si lo supera, devuelve el carry desactivado y no añade la solicitud.
# Utiliza <code>DX_PPU_VRAM_Transfer_Length</code> para encontrar la siguiente entrada y aumenta ese contador en 1.
# Guarda el origen, banco, cantidad de bytes y destino en las tablas.
# Actualiza <code>DX_Dynamic_CurrentDataSend</code> con los bytes de la carga y devuelve el carry activado.

<code>%ForcedTransferToVRAM()</code> guarda los mismos datos, pero no comprueba el límite de bytes. Las variantes <code>FromAddr</code> y <code>Resource</code> facilitan obtener el origen desde una dirección completa o desde los defines de un recurso.

Añadir una solicitud no copia los gráficos inmediatamente: deja la información preparada para NMI.

=== Ejecutar las solicitudes durante NMI ===

La rutina <code>VRAMDMA</code>:

# Lee <code>DX_PPU_VRAM_Transfer_Length</code>. Si es 0, termina porque no hay solicitudes.
# Calcula el desplazamiento de la última entrada: <code>(Length - 1) × 2</code>.
# Lee su origen, banco y cantidad de bytes, y los coloca en los registros de DMA.
# Escribe el destino de VRAM en <code>$2116-$2117</code> e inicia la transferencia mediante <code>$420B</code>.
# Retrocede 2 bytes para procesar la solicitud anterior. Repite hasta completar la primera.
# Escribe 0 en <code>DX_PPU_VRAM_Transfer_Length</code> para indicar que la lista está vacía.

'''La lista se ejecuta del final al inicio.''' No hace falta borrar todos sus datos al terminar: al quedar su largo en 0, la próxima solicitud volverá a utilizar la primera entrada.

=== Animaciones con un destino fijo ===

El código de una animación debe:

# Elegir la imagen que corresponde al paso actual.
# Calcular su dirección de origen.
# Solicitar la copia al destino de VRAM de la animación.
# Comprobar el carry. Si se rechaza la carga, conservar la imagen anterior y volver a intentarlo.

El destino puede ser siempre el mismo. Lo que cambia es la imagen que se copia allí; la lista de transferencias no decide cuándo debe avanzar la animación.

Puedes ver un código completo en [[es/Dynamic_Xtreme_UberASM_guide#Crear_animaciones_de_gráficos|Crear animaciones de gráficos de la guía de UberASM]].

=== Carga de una pose dinámica ===

La carga de una pose utiliza la caché para no repetir transferencias de gráficos que ya están disponibles:

# Busca el ID en la tabla hash.
# Si ya está registrado, actualiza su tiempo de uso y no añade otra carga.
# Si no está, comprueba la cantidad de bytes y busca un espacio adecuado en el mapa de VRAM.
# Elige qué poses pueden reemplazarse, teniendo en cuenta su tiempo sin uso y el espacio que necesita la nueva.
# Actualiza las tablas de la caché y el mapa.
# <code>DynamicRoutine</code> divide los datos de la pose en las transferencias necesarias.
# NMI ejecuta esas transferencias.

Cada paso se desarrolla en [[#Sprites_dinámicos:_DynamicPoses|Sprites dinámicos: DynamicPoses]], incluyendo la búsqueda por hash, el mapa, la política de reemplazo y la división de la carga en filas.

== Carga y asignación de paletas: PalettesChange ==

El sistema distingue dos valores:

* '''ID de paleta:''' identifica los colores guardados en ROM.
* '''Destino de pantalla:''' indica qué paleta de CGRAM utilizará esos colores.

La asignación automática permite compartir colores entre sprites sin exigir un destino fijo para cada uno.

=== Lista de cargas a CGRAM ===

En esta tabla, '''C''' es <code>!CGRAMTransferSize</code>: 64 por defecto. El conjunto reserva <code>1 + 7 × C</code> bytes, es decir, 449 con ese valor. Aunque <code>SourceBNK</code> reserva 2 × C bytes, el código utiliza un byte de banco por solicitud.

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_PPU_CGRAM_Transfer_Length</code> || 1 || 1 || Índice de la última solicitud pendiente. <code>$FF</code> indica una lista vacía; 0 indica que hay una solicitud.
|-
| <code>DX_PPU_CGRAM_Transfer_Source</code> || 2 × C; 128 por defecto || 2 || Dirección de origen, sin el banco.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceBNK</code> || 2 × C; 128 reservados por defecto || 1 utilizado por solicitud || Banco del origen.
|-
| <code>DX_PPU_CGRAM_Transfer_SourceLength</code> || 2 × C; 128 por defecto || 2 || Cantidad de bytes que se copiarán. Cada color ocupa 2 bytes.
|-
| <code>DX_PPU_CGRAM_Transfer_Offset</code> || C; 64 por defecto || 1 || Primer color de destino en CGRAM.
|}

Durante NMI, <code>CGRAMDMA</code>:

# Comienza por la última solicitud pendiente.
# Configura DMA con el origen y la cantidad de bytes de esa solicitud.
# Selecciona el primer color mediante <code>$2121</code> y realiza la copia.
# Continúa con las solicitudes anteriores.
# Al terminar, escribe <code>$FF</code> en <code>DX_PPU_CGRAM_Transfer_Length</code>.

Las macros <code>TransferPalette</code> también actualizan las copias de colores y el estado de efectos:

* '''Sin efecto global:''' solicitan la carga y actualizan los buffers de SMW. Así el juego no vuelve a utilizar colores anteriores durante la animación de victoria del goal.
* '''Con efecto global:''' guardan los colores originales y preparan el estado necesario para aplicarles el efecto antes de enviarlos a CGRAM.

=== Asignación automática ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_ID</code> || 32 || 2 || Guarda el ID asignado a cada destino. <code>$FFFF</code> indica una entrada libre y <code>$FFFE</code> una reservada.
|-
| <code>DX_Dynamic_Palettes_DisableTimer</code> || 16 || 1 || Protege cada destino del reemplazo automático mientras está en uso.
|-
| <code>DX_Dynamic_Palettes_EffectEnabled</code> || 1 || 1; un bit por paleta de sprites || Indica qué paletas de sprites están asignadas con efecto global habilitado. Esta condición también se compara al compartir una asignación.
|}

La búsqueda sigue este orden:

# Reutilizar una asignación con el mismo ID y una condición de efecto compatible.
# Si no existe, utilizar una entrada libre.
# Si no hay entradas libres, reemplazar una que no esté reservada y cuyo temporizador sea 0.
# Si no encuentra ninguna, indicar que la asignación falló.

Mientras el recurso utiliza la paleta, mantiene su temporizador en 2. Llegar a 0 no borra los colores: la asignación puede reutilizarse si otro recurso todavía no la reemplazó.

=== Asignación manual y versión ===

* '''Manual con carga:''' el código elige el destino y solicita sus colores.
* '''Manual sin carga:''' el código elige el destino y utiliza los colores que ya estaban preparados.
* '''Versión:''' selecciona una entrada de la lista de paletas del DynamicInfo. La última versión procesada permite comprobar si esa selección cambió.

Dos recursos que elijan el mismo destino con colores distintos deben coordinarse. Mantener la protección de una paleta no significa volver a cargar sus colores.

== Dibujo de poses: DrawingSystem ==

El dibujo prepara las piezas de una pose en OAM: qué tiles se muestran, dónde se colocan y qué propiedades utilizan. Los datos gráficos deben estar en VRAM.

=== Pasos del dibujo ===

# Busca la rutina y los datos de la pose mediante <code>GraphicRoutineIDs</code>, <code>GraphicRoutine</code> y <code>TableOffset</code>.
# Obtiene la cantidad de piezas desde <code>NumberOfTilesMinus1</code>.
# Calcula la posición de cada tile usando la posición del sprite, sus desplazamientos y los volteos que correspondan.
# Comprueba si la pieza puede verse y si queda espacio de OAM.
# Escribe su posición, número de tile, propiedades y tamaño en los buffers OAM.

El número de tile depende del dibujo:

{| class="wikitable"
! Caso !! Cómo se obtiene el tile
|-
| Pose dinámica || Se ajusta al lugar de VRAM donde quedaron cargados sus gráficos.
|-
| Pose estática || Se utiliza su número de tile fijo.
|-
| Pose que utiliza un tile común || El código debe preparar <code>!Tile</code> antes de llamar al dibujo.
|}

=== Prioridad y espacio disponible ===

* En '''LoROM''', el sistema lleva su propio control de entradas OAM disponibles.
* En '''SA-1''', utiliza la integración con MaxTile.
* La '''prioridad de dibujo''' organiza las piezas de sprites. No es la misma propiedad que determina si un tile queda delante o detrás de las capas.
* Los '''límites por línea de pantalla''' de SNES siguen existiendo. Tener una pose cargada no garantiza que puedan verse todas sus piezas.

== Jugador y Yoshi ==

=== PlayerFeatures ===

El jugador original tiene rutinas propias para elegir y cargar las piezas de sus poses. <code>PlayerFeatures</code> permite integrar ese trabajo con las cargas de Dynamic Xtreme y cambiar el origen de sus gráficos y paletas.

Con el formato original, el juego sigue eligiendo las piezas de la pose. La rutina obtiene sus direcciones desde el origen configurado y compara esas direcciones con las anteriores para cargar las que hayan cambiado.

Estas cargas utilizan transferencias forzadas y sus bytes también cuentan para las solicitudes normales posteriores. Así conservan su prioridad sin quedar fuera de la contabilidad del sistema.

La paleta del jugador tiene un tratamiento especial: combina colores y selecciones del propio juego con el origen personalizado. No funciona simplemente como sustituir una paleta completa de un sprite cualquiera.

El soporte para jugadores personalizados permite que otros sistemas administren de otra forma sus poses y dibujo. No convierte automáticamente cualquier spritesheet al formato del jugador original.

=== YoshiFeatures ===

Yoshi también carga sus gráficos por piezas. <code>YoshiFeatures</code> permite cambiar su origen manteniendo la organización que esperan sus rutinas.

El código calcula qué partes necesita y prepara sus cargas a los destinos correspondientes de VRAM. Como las del jugador, estas cargas tienen un tratamiento prioritario.

Esta opción necesita <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad. No permite evitar un conflicto del sistema del jugador habilitando únicamente las funciones de Yoshi.

== Memoria y optimizaciones ==

=== Free7E2000 ===

SMW mantiene en RAM gráficos originales del jugador, Yoshi y ciertas animaciones. En ROMs sin SA-1, esta opción adapta las cargas para leer esos datos desde ROM.

Dynamic Xtreme aprovecha la RAM recuperada para sus variables internas. No es un espacio que quede libre para que cualquier otro código escriba encima.

SA-1 utiliza otras direcciones y desactiva esta opción. Los rangos están en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Espacios de RAM utilizados]].

=== ControllerOptimization ===

Esta opción mueve el procesamiento del control desde NMI a la parte de game mode. El objetivo es dejar más tiempo para las actualizaciones de pantalla, no añadir un frame de retraso ni cambiar los botones que recibe el juego.

=== FixedColorOptimization ===

El color fijo se utiliza en las mezclas de color de la consola. Para actualizarlo, el juego prepara sus componentes y los envía al registro correspondiente.

La optimización reemplaza esa preparación por una secuencia más corta. El color sigue enviándose a la consola, pero necesita menos trabajo durante NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic utiliza listas llamadas stripe images para actualizar partes de los mapas de tiles. Esas listas incluyen tanto los datos como la información sobre sus destinos.

La versión integrada de la optimización de Kevin prepara fuera de NMI parte del ajuste de esos destinos. Así deja menos trabajo de preparación para el momento de la transferencia.

Esta opción sustituye el uso del parche original por separado. Además, no debe desinstalarse después de instalarla; hay que tenerlo en cuenta antes de activarla.

=== StatusBarOptimization ===

La barra de estado original actualiza zonas concretas de VRAM. Esta opción prepara sus transferencias de forma más directa, reduciendo la configuración de DMA que necesita hacer durante NMI.

No añade una barra nueva. Modifica la actualización de la original y, por eso, entra en conflicto con recursos que la reemplazan, modifican o eliminan.

== Sprites dinámicos: DynamicPoses ==

El sistema funciona como una '''caché de poses en VRAM'''. No reserva una copia de los gráficos para cada sprite: guarda la pose y permite que la reutilicen todos los recursos que la necesiten.

* Una pose se carga una sola vez mientras permanezca en la caché.
* Las siguientes solicitudes actualizan su tiempo de último uso, sin añadir otra carga de sus gráficos.
* La pose no se borra cuando un recurso deja de utilizarla. Permanece allí hasta que se necesite su espacio y se elija reemplazarla.
* Si fue reemplazada y vuelve a solicitarse, tendrá que cargarse otra vez.

La elección no depende de cuánto tiempo lleva la pose desde que se cargó, sino de '''cuánto tiempo lleva sin utilizarse''' y de si su espacio sirve para la pose nueva.

=== Tres valores distintos ===

{| class="wikitable"
! Valor !! Qué identifica
|-
| ID de pose || La pose instalada. Tiene 16 bits y permite consultar sus datos en ROM.
|-
| Índice de la tabla hash || La entrada de RAM donde se registró la pose. Va de 0 a 127.
|-
| Bloque de VRAM || La posición donde comienzan sus gráficos dentro del espacio de sprites. Va de 0 a 127.
|}

El índice de la tabla hash y el bloque de VRAM no tienen por qué coincidir. Una entrada de la tabla puede registrar una pose que empieza en cualquier bloque permitido.

=== Tablas de las poses registradas ===

{| class="wikitable"
! Variable o tabla !! Bytes totales !! Bytes por valor !! Qué guarda
|-
| <code>DX_Dynamic_Pose_Length</code> || 1 || 1 || Cantidad de poses registradas.
|-
| <code>DX_Dynamic_Pose_HashSize</code> || 128 || 1 || Cantidad de poses registradas para cada hash.
|-
| <code>DX_Dynamic_Pose_ID</code> || 256 || 2 || ID completo de la pose de cada entrada. <code>$FFFF</code> indica una entrada libre.
|-
| <code>DX_Dynamic_Pose_Offset</code> || 128 || 1 || Bloque de VRAM donde comienza cada pose.
|-
| <code>DX_Dynamic_Pose_TimeLastUse</code> || 256 || 2 || Valor de <code>DX_Timer</code> de su último uso.
|}

Estas tablas ocupan '''769 bytes''' en RAM. Guardan las poses registradas durante el juego; las tablas generadas desde el DynamicInfo describen, en cambio, todas las poses instaladas.

=== Cómo se busca una pose ===

La rutina <code>DynamicPoseHashmap_FindPose</code> utiliza una tabla hash de 128 entradas. El hash permite elegir dónde empezar a buscar:

<pre>
hash = ID de pose AND $007F
</pre>

Dos IDs diferentes pueden tener el mismo hash. Por ejemplo, <code>$0005</code> y <code>$0085</code> producen <code>$05</code>. Por eso el hash no basta para confirmar que la pose está cargada: también se compara el ID completo.

La búsqueda sigue estos pasos:

# Guarda el ID solicitado y calcula su hash.
# Si <code>DX_Dynamic_Pose_Length</code> es 0, no hay poses registradas y la búsqueda termina.
# Consulta <code>DX_Dynamic_Pose_HashSize[hash]</code>. Si es 0, ninguna pose registrada tiene ese hash y también termina.
# Comienza por la entrada cuyo índice coincide con el hash.
# Lee el ID de esa entrada. Si coincide con el solicitado, encontró la pose.
# Si no coincide, continúa con la siguiente entrada de la secuencia de búsqueda.

La secuencia avanza '''15 entradas por intento''' y vuelve al comienzo al superar 127:

<pre>
siguiente índice = (índice actual + 15) AND $7F
</pre>

Con 128 entradas, ese paso permite visitar todas las posiciones antes de repetir una. Para el hash <code>$05</code>, el comienzo de la secuencia es:

<pre>
$05 → $14 → $23 → $32 → $41 → ...
</pre>

El sistema no necesita recorrer siempre las 128 entradas. <code>DX_Dynamic_Pose_HashSize</code> indica cuántas poses de ese hash hay que comprobar. Al encontrar una pose distinta con el mismo hash, descuenta una del contador de búsqueda; si ya comprobó todas sin encontrar el ID solicitado, termina.

'''Una entrada libre no termina la búsqueda.''' Puede haber quedado vacía al reemplazar una pose y existir otra del mismo hash más adelante. Las entradas de otros hashes tampoco descuentan el contador de poses que faltan por comprobar.

==== Cuando encuentra la pose ====

<code>TakeDynamicRequest</code>:

# Obtiene el índice de la entrada encontrada.
# Escribe el valor actual de <code>DX_Timer</code> en <code>DX_Dynamic_Pose_TimeLastUse</code> para esa entrada.
# Devuelve el éxito de la solicitud, sin volver a programar la carga de sus gráficos.

Así todos los recursos que solicitan ese ID utilizan la misma pose y la mantienen protegida. No importa si el recurso es un sprite normal, cluster, extended u otro código que utiliza el sistema.

Esto también evita duplicar una carga dentro del mismo ciclo: cuando la primera solicitud se acepta, la pose ya queda registrada aunque la transferencia física se vaya a realizar durante NMI.

=== Cuando la pose no está registrada ===

<code>TakeDynamicRequest</code> continúa con la preparación de una carga nueva:

# Consulta <code>PoseSize</code> y calcula <code>DX_Dynamic_CurrentDataSend + PoseSize</code>.
# Si supera <code>DX_Dynamic_MaxDataPerFrame</code>, termina con fallo, sin cambiar las poses existentes.
# Consulta <code>Pose16x16Blocks</code> para saber cuántos bloques necesita.
# Llama a <code>VRAMMap_GetBestSlot</code> para buscar un espacio adecuado.
# Si no existe un espacio utilizable, termina con fallo.
# Retira del mapa y de la tabla hash las poses que ocupen el espacio elegido.
# Busca una entrada libre de la tabla hash y registra la pose nueva.
# Actualiza el mapa de VRAM y el contador de datos del frame.
# Llama a <code>DynamicRoutine</code> para añadir las transferencias.

El presupuesto se comprueba antes de reemplazar poses. Si la nueva carga no cabe en el frame, no se libera espacio para una solicitud que no se puede atender.

==== Añadir y quitar entradas de la tabla hash ====

* <code>DynamicPoseHashmap_FindFreeSpace</code> busca una entrada cuyo ID sea <code>$FFFF</code>, siguiendo la misma secuencia de pasos de 15.
* <code>DynamicPoseHashmap_Add</code> guarda el ID y su tiempo de uso, aumenta <code>DX_Dynamic_Pose_Length</code> y aumenta el contador de su hash.
* <code>DynamicPoseHashmap_Remove</code> escribe <code>$FFFF</code> en el ID retirado y reduce ambos contadores.

Retirar una entrada no borra por sí solo los píxeles de VRAM. Indica que esa pose dejó de estar disponible en la caché; las nuevas transferencias sobrescribirán el espacio elegido.

=== Cómo se representa el mapa de VRAM ===

El mapa tiene '''128 bloques''' de gráficos de 16×16. En 4bpp, un bloque completo equivale a 128 bytes de gráficos. Las poses incompletas pueden copiar menos datos, pero necesitan reservar los bloques que ocupan.

{| class="wikitable"
! Tabla !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_Dynamic_Tile_Offset</code> || 128 || 1 || Bloque donde comienza la región. El bit <code>$80</code> indica que está reservada.
|-
| <code>DX_Dynamic_Tile_Size</code>, también llamada <code>DX_Dynamic_Tile_Pose</code> || 128 || 1 || Si el bit <code>$80</code> está activo, los otros bits guardan el tamaño de la región libre menos uno. Si está desactivado, guardan el índice de la pose en la tabla hash.
|}

Son '''256 bytes''' adicionales. Junto con las tablas de poses, el administrador utiliza '''1025 bytes''' de RAM, sin contar las listas de DMA ni las scratch de trabajo.

El mapa guarda la información en los extremos de cada región: su primer y su último bloque. No necesita mantener un registro independiente de la pose en cada bloque intermedio.

Por ejemplo, una región libre de 6 bloques, desde <code>$20</code> hasta <code>$25</code>, guarda en ambos extremos:

* <code>Offset = $20</code>: comienzo de la región.
* <code>Size = $85</code>: bit de región libre <code>$80</code> más el tamaño menos uno, <code>$05</code>.

Si la región está ocupada, el tamaño se obtiene consultando el ID de su entrada hash y después <code>Pose16x16Blocks</code>.

Las configuraciones de <code>DynamicPoseSpaceConfig</code> preparan las regiones disponibles y reservadas de SP1-SP4. Una región reservada no puede elegirse para una pose nueva.

=== Recorrido y búsqueda de espacio ===

<code>VRAMMap_GetBestSlot</code> comienza en el bloque <code>$7F</code> y recorre las regiones hacia atrás:

# Lee el comienzo de la región desde <code>DX_Dynamic_Tile_Offset</code>.
# Comprueba si está reservada.
# Obtiene su tamaño y su puntuación de tiempo sin uso.
# Comprueba si sirve para la pose solicitada o si debe considerar también una región contigua.
# Para pasar a la región anterior, utiliza <code>comienzo de la región - 1</code>.

El registro del último bloque permite saltar regiones completas. No se recorren uno por uno todos los bloques que ocupa una pose.

Durante la búsqueda se conservan los datos del espacio que se está evaluando y del mejor encontrado:

{| class="wikitable"
! Datos de trabajo !! Bytes totales !! Bytes por valor !! Para qué se usan
|-
| <code>VRAMMapCurrentSpace</code> || 3 || 1 por campo || Comienzo, puntuación y cantidad de bloques del candidato actual.
|-
| <code>VRAMMapBestSpace</code> || 3 || 1 por campo || Los mismos campos para el mejor candidato encontrado.
|-
| <code>VRAMMapTMP_Size</code> || 1 || 1 || Cantidad de bloques que necesita la pose nueva.
|}

Estos nombres son datos temporales en scratch, no reservas adicionales de RAM persistente.

=== Política de reemplazo: tiempo sin uso y espacio suficiente ===

El sistema no elige simplemente la pose que se cargó primero. Utiliza el tiempo transcurrido desde su '''último uso''':

<pre>
tiempo sin uso = DX_Timer - TimeLastUse de la pose
</pre>

<code>VRAMMapSlot_GetSizeAndScore</code> obtiene el tamaño y una puntuación para cada región:

{| class="wikitable"
! Caso !! Puntuación y tratamiento
|-
| Región libre || <code>$FF</code>. Se favorece frente a regiones ocupadas.
|-
| Región ocupada || Tiempo sin uso, limitado a <code>$FE</code>.
|-
| Tiempo sin uso de 0 o 1 || No se puede reemplazar: la pose sigue protegida.
|-
| Región reservada || Se descarta, independientemente del tiempo sin uso.
|}

La protección exige '''al menos dos avances de <code>DX_Timer</code> sin utilizar la pose'''. Cada recurso que vuelve a solicitarla actualiza su tiempo de uso y vuelve a protegerla.

==== Por qué no siempre se reemplaza la pose con más tiempo sin uso ====

La pose nueva necesita espacio suficiente y contiguo. Un espacio pequeño no sirve por sí solo, aunque lleve mucho tiempo sin utilizarse.

Por ejemplo, para una pose nueva de 4 bloques:

{| class="wikitable"
! Espacio candidato !! Tiempo sin uso !! ¿Sirve?
|-
| Pose A: 2 bloques, sin espacio contiguo utilizable || 20 || No: solo deja 2 bloques.
|-
| Pose B: 4 bloques || 8 || Sí: puede alojar la pose nueva.
|}

En este caso se puede reemplazar B y conservar A. A lleva más tiempo sin uso, pero su espacio no permite atender la solicitud.

Si dos o más regiones contiguas pueden reemplazarse, el sistema puede considerarlas juntas. Para esa combinación:

* Suma sus cantidades de bloques.
* Utiliza la '''menor puntuación''' de las regiones combinadas, es decir, el menor tiempo sin uso.
* Si una está reservada o protegida, no puede utilizarla para completar el espacio.

Así una pose usada recientemente no puede quedar sobrescrita por combinarla con otra que lleva mucho tiempo sin uso.

==== Elegir entre candidatos válidos ====

# El candidato debe tener al menos la cantidad de bloques solicitada.
# Se prefiere la puntuación más alta: espacio libre o mayor tiempo sin uso.
# Si las puntuaciones son iguales, se prefiere el candidato con menos bloques, siempre que la pose quepa.
# Si puntuación y tamaño también coinciden, se conserva el candidato que ya se había elegido.

Las regiones se combinan durante la búsqueda cuando el candidato todavía es demasiado pequeño. No se juntan todas las regiones reemplazables sin tener en cuenta el tamaño solicitado.

=== Reemplazar y dividir la región elegida ===

Una vez elegido el espacio:

# <code>VRAMMap_RemovePosesInSpace</code> recorre sus regiones y retira de la tabla hash las poses que haya que reemplazar.
# <code>VRAMMap_RemoveSpace</code> representa el espacio elegido como una región libre, actualizando sus extremos.
# Se busca una entrada hash libre y se guarda el bloque de comienzo en <code>DX_Dynamic_Pose_Offset</code>.
# <code>DynamicPoseHashmap_Add</code> registra la pose.
# <code>VRAMMap_AddPoseInSpace</code> escribe el índice hash de la pose y el comienzo de su región en el primer y último bloque.
# Si sobran bloques, crea otra región libre con el resto.

Si una región de 6 bloques aloja una pose de 4, quedan una región ocupada de 4 y una libre de 2. No se mueven las demás poses para compactar VRAM.

=== DynamicRoutine: preparar las transferencias de la pose ===

En este punto ya se eligió el espacio y se registró la pose. <code>DynamicRoutine</code> convierte esa asignación en solicitudes de transferencia.

Utiliza estos datos:

{| class="wikitable"
! Dato !! Cantidad consultada por pose !! Para qué sirve
|-
| Bloque de comienzo || 1 byte || Lugar elegido por el mapa de VRAM.
|-
| <code>OffsetToVRAMOffset</code> || 2 bytes de una tabla de 256 bytes || Convierte uno de los 128 bloques en un desplazamiento de VRAM.
|-
| <code>PoseResource</code> || 3 bytes || Dirección completa de los datos de la pose en ROM.
|-
| <code>PoseResourceSizePerLine</code> || 4 bytes: dos valores de 2 || Cantidad de bytes del primer y del segundo tramo.
|-
| <code>PoseSecondLineOffset</code> || 2 bytes || Desplazamiento de VRAM para el segundo tramo.
|}

==== Convertir el bloque en una dirección de VRAM ====

Los bloques de 16×16 no se convierten simplemente en un desplazamiento lineal de bytes. Cada uno utiliza tiles de 8×8 distribuidos en las filas de VRAM.

<code>OffsetToVRAMOffset</code> contempla esa distribución. Por ejemplo:

{| class="wikitable"
! Bloque !! Desplazamiento !! Dirección de VRAM
|-
| <code>$00</code> || <code>$0000</code> || <code>$6000</code>
|-
| <code>$01</code> || <code>$0020</code> || <code>$6020</code>
|-
| <code>$08</code> || <code>$0200</code> || <code>$6200</code>
|}

Estas direcciones de VRAM están expresadas en palabras de 2 bytes, no en bytes. La rutina suma la base <code>$6000</code> utilizada para los gráficos de sprites.

==== Procesar los tramos y sus filas ====

# Obtiene el origen desde <code>PoseResource</code>.
# Procesa los bytes del primer tramo mediante <code>DynamicRoutineLine</code>.
# Si el segundo tramo tiene tamaño 0, termina.
# Si existe, adelanta el origen la cantidad de bytes del primer tramo.
# Suma <code>PoseSecondLineOffset</code> al desplazamiento de VRAM y procesa el segundo tramo.

<code>DynamicRoutineLine</code> divide cada tramo según las filas y el punto de comienzo. Para un destino V expresado en palabras de VRAM, prepara:

<pre>
Final de la primera fila = (V + $0100) AND $FF00
Bytes hasta ese final = (final de la primera fila - V) × 2
Destino de la segunda parte = final de la primera fila + $0100
Bytes de la segunda parte de un grupo = $0200 - bytes de la primera
</pre>

Los tamaños son cantidades de bytes, mientras que los destinos de VRAM están expresados en palabras. Por eso se multiplica por 2 al calcular cuántos datos caben hasta el final de una fila.

La rutina utiliza tres recorridos:

* <code>.EndLine</code>: añade una solicitud final con los bytes restantes.
* <code>.TwoLinesWithEndLine</code>: añade dos solicitudes para los datos restantes, cada una con su destino y cantidad de bytes.
* <code>.TwoLines</code>: añade dos solicitudes que suman <code>$0200</code> bytes, avanza el origen y los destinos y repite con los datos que faltan.

Hay un caso directo antes del recorrido general: si el destino comienza en un límite de <code>$0100</code> palabras y el tramo tiene al menos <code>$0200</code> bytes, la rutina utiliza <code>.EndLine</code> para preparar la copia del tramo completo en una solicitud.

Por ejemplo, un tramo de <code>$0200</code> bytes que comienza en <code>$6020</code> se divide así:

{| class="wikitable"
! Solicitud !! Origen !! Destino VRAM !! Bytes
|-
| Primera || Comienzo del tramo || <code>$6020</code> || <code>$01C0</code>: 448
|-
| Segunda || Comienzo del tramo + <code>$01C0</code> || <code>$6200</code> || <code>$0040</code>: 64
|}

Las dos solicitudes copian los 512 bytes del tramo, respetando los destinos que calcula la distribución de filas. No son dos copias completas de la pose.

Cada solicitud utiliza estas tablas:

* <code>DX_PPU_VRAM_Transfer_Source</code>
* <code>DX_PPU_VRAM_Transfer_SourceBNK</code>
* <code>DX_PPU_VRAM_Transfer_SourceLength</code>
* <code>DX_PPU_VRAM_Transfer_Offset</code>

Por cada solicitud añadida aumenta <code>DX_PPU_VRAM_Transfer_Length</code>.

La cantidad total de bytes de la pose ya se comprobó y se añadió a <code>DX_Dynamic_CurrentDataSend</code> en <code>TakeDynamicRequest</code>. Esta parte divide esa carga en transferencias; no vuelve a contar la pose completa por cada solicitud.

<code>DynamicRoutine</code> '''no ejecuta DMA'''. Deja las solicitudes preparadas para que <code>VRAMDMA</code> las copie durante NMI.

=== Qué conserva el sprite ===

Las rutinas de sprites guardan el índice hash de la pose utilizable, no una copia independiente de sus gráficos. Ese índice permite consultar su bloque de VRAM y mantener actualizado su tiempo de uso.

Si una pose nueva no puede cargarse:

* Si existe una pose anterior válida, se mantiene y se actualiza su tiempo de uso para protegerla.
* Si nunca hubo una pose válida, no se debe dibujar como si la solicitud hubiera tenido éxito.
* En las llamadas con soporte para mantener la anterior, el carry puede indicar que todavía hay una pose utilizable aunque no se haya completado el cambio.

La animación y el movimiento siguen siendo responsabilidad del sprite. La caché se ocupa de reutilizar o preparar los gráficos solicitados.

== Efectos de paleta: PalettesEffects ==

El sistema conserva los colores originales para poder cambiar de efecto, combinarlo con otro o volver a la paleta sin efecto. No debe utilizar el resultado ya afectado como si fuera la paleta original.

=== Buffers de colores ===

{| class="wikitable"
! Variable o buffer !! Bytes totales !! Bytes por valor !! Contenido
|-
| <code>DX_PPU_CGRAM_PaletteCopy</code> || 512 || 2 por color || Colores de base en formato SNES, con 2 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseRGBPalette</code> || 768 || 3 por color || Base separada en rojo, verde y azul, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_BaseHSLPalette</code> || 768 || 3 por color || Base separada en tono, saturación y luminosidad, con 3 bytes por color.
|-
| <code>DX_PPU_CGRAM_PaletteWriteMirror</code> || 512 || 2 por color || Resultado en formato SNES, listo para solicitar su copia a CGRAM. Corresponde al buffer de paletas del juego.
|}

=== Indicadores de cada paleta ===

Cada bit de estos indicadores corresponde a una paleta. Las variables <code>BG</code> cubren 0-7 y las <code>SP</code> cubren 8-F.

{| class="wikitable"
! Variables !! Bytes totales !! Bytes por valor !! Qué indican
|-
| <code>DX_PPU_CGRAM_BGBaseLoaded</code> y <code>DX_PPU_CGRAM_SPBaseLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si ya se preparó la base de colores en formato SNES.
|-
| <code>DX_PPU_CGRAM_BGBaseRGBPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseRGBPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a RGB.
|-
| <code>DX_PPU_CGRAM_BGBaseHSLPaletteLoaded</code> y <code>DX_PPU_CGRAM_SPBaseHSLPaletteLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparada la conversión de la base a HSL.
|-
| <code>DX_PPU_CGRAM_BGEffectLoaded</code> y <code>DX_PPU_CGRAM_SPEffectLoaded</code> || 1 por variable; 2 entre ambas || 1; un bit por paleta || Si está preparado el resultado del efecto global.
|}

Estos indicadores evitan repetir conversiones y cálculos que siguen siendo válidos.

=== Preparar una base ===

# Se comprueba si la paleta ya tiene una base registrada.
# Si no la tiene, se obtienen los colores del buffer del juego. Una carga explícita, como <code>TransferPalette</code>, puede proporcionar esa base directamente.
# Se comprueba si el efecto necesita RGB o HSL.
# Si falta esa conversión, se prepara y se marca como disponible.

Si solo cambia el efecto, la base puede seguir siendo válida. Si cambian los colores originales, las llamadas de carga actualizan la base e invalidan las conversiones y resultados que deben calcularse otra vez.

=== Datos de un efecto ===

El ID permite consultar las tablas generadas durante la instalación:

* <code>Types</code>: cálculo que debe realizarse.
* <code>Value1</code>, <code>Value2</code> y <code>Value3</code>: valores de los canales o dirección de la paleta de destino de una transición.
* <code>Ratio1</code>, <code>Ratio2</code> y <code>Ratio3</code>: cuánto se aplica cada cambio.

Los canales utilizan valores de 0 a 31. Los ratios van de 0 a 127: 0 conserva el origen y 127 aplica por completo el cambio elegido.

Los cálculos se realizan fuera de NMI. NMI realiza la transferencia de los colores resultantes.

=== Efecto global ===

{| class="wikitable"
! Variable !! Bytes totales !! Bytes por valor !! Para qué sirve
|-
| <code>DX_Dynamic_Palettes_GlobalEffectID</code> || 2 || 2 || Selecciona el efecto global. El valor 0 permite restaurar los colores de base.
|-
| <code>DX_Dynamic_Palettes_GlobalBGEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 0-7 que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_GlobalSPEnable</code> || 1 || 1; un bit por paleta || Selecciona las paletas 8-F que reciben el efecto.
|-
| <code>DX_Dynamic_Palettes_LastGlobalEffectIDPerPal</code> || 32 || 2 || Guarda el último ID global procesado por cada paleta.
|-
| <code>DX_PPU_ColorEffect_Enable</code> || 1 || 1 || Controla la participación del color fijo y el color 0,0.
|}

Para cada paleta habilitada, el administrador:

# Comprueba si necesita actualizar el resultado del efecto.
# Prepara la base RGB o HSL si todavía falta.
# Calcula el efecto si el resultado anterior ya no sirve.
# Prepara los colores en formato SNES y solicita su transferencia.
# Confirma el ID procesado cuando la carga correspondiente se acepta.

Si se mantiene el mismo efecto y no cambió la base, no hace falta calcularlo otra vez. Al cambiar el ID global se invalidan los resultados anteriores, no necesariamente las bases RGB y HSL.

El ID global 0 también requiere una actualización: el sistema debe cargar de nuevo los colores de base para quitar el efecto anterior.

=== Efecto local y concatenación ===

Un recurso puede tener un efecto propio y recibir también el global. Por ejemplo, un sprite puede cambiar de tono y después oscurecerse junto con el nivel.

El orden es:

# Preparar el resultado del efecto local.
# Utilizarlo como base para el efecto global mediante la llamada de concatenación.
# Calcular el efecto global sobre esa base.
# Cargar el resultado combinado, sin mostrar antes la versión que solo tiene el efecto local.

* La concatenación RGB se utiliza con efectos RGB.
* La concatenación HSL se utiliza con efectos HSL.
* Los recursos que comparten un destino de CGRAM comparten sus colores. Para mostrar dos efectos locales distintos, necesitan destinos que permitan mantener ambos resultados.

=== Si no se acepta la transferencia ===

* Calcular el efecto no significa que ya esté en CGRAM.
* Si la transferencia no se acepta, el administrador puede volver a intentar la actualización.
* Cuando corresponde, se mantiene el resultado anterior utilizable hasta poder sustituirlo.
* No se deben cargar primero los colores originales sin efecto: podrían verse así durante un frame antes del resultado correcto.

== Cómo trabajan juntos ==

El recorrido de un sprite dinámico reúne estas tareas:

# Su lógica elige la pose y la versión de paleta.
# La asignación busca una paleta utilizable y prepara los colores si hace falta.
# La caché protege la pose ya cargada o prepara la carga de una nueva.
# El dibujo escribe los datos de sus piezas en los buffers OAM.
# El administrador de efectos prepara los cambios globales pendientes.
# NMI realiza las transferencias de gráficos y colores solicitadas.

Compartir gráficos, compartir una paleta y compartir una rutina de dibujo son tres cosas distintas. Dynamic Xtreme puede aprovechar cada una sin obligar a que los recursos compartan también las demás.

== Lecturas relacionadas ==

* [[es/Dynamic_Xtreme|Artículo principal]]: funcionalidades y compatibilidad.
* [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos]].
* [[es/Dynamic_Xtreme_sprite_creation_guide|Creación de sprites dinámicos]].
* [[es/Dynamic_Xtreme_UberASM_guide|Dynamic Xtreme con UberASM]].
* [[es/Dynamic_Xtreme_ASM_API|API ASM]].

es/Dynamic Xtreme internal workings

2026-10-25T02:21:37Z

Anonimzwx:

es/Dynamic Xtreme internal workings

2026-10-25T01:52:01Z

Anonimzwx:

es/Dynamic Xtreme internal workings

2026-10-25T01:39:13Z

Anonimzwx:

es/Dynamic Xtreme internal workings

2026-10-25T01:31:05Z

Anonimzwx:

es/Dynamic Xtreme internal workings

2026-10-25T01:19:20Z

Anonimzwx:

es/Dynamic Xtreme internal workings

2026-10-25T01:12:28Z

Anonimzwx: Created page with "{{Select Language|Dynamic_Xtreme_internal_workings}} En este artículo se explica cómo funciona Dynamic Xtreme por dentro: cómo prepara las cargas de gráficos y paletas, cómo aprovecha NMI y cómo coordina el dibujo, las poses dinámicas y los efectos de color. Los apartados comienzan con el recorrido general de un frame y los sistemas de carga. Después se explican las funcionalidades que aprovechan esos sistemas, hasta llegar a la caché de poses y los efectos de..."

{{Select Language|Dynamic_Xtreme_internal_workings}}

En este artículo se explica cómo funciona Dynamic Xtreme por dentro: cómo prepara las cargas de gráficos y paletas, cómo aprovecha NMI y cómo coordina el dibujo, las poses dinámicas y los efectos de color.

Los apartados comienzan con el recorrido general de un frame y los sistemas de carga. Después se explican las funcionalidades que aprovechan esos sistemas, hasta llegar a la caché de poses y los efectos de paleta.

== Organización general ==

Dynamic Xtreme tiene dos partes que trabajan en momentos distintos:

* '''La herramienta de instalación''' lee los recursos, prepara sus datos, genera defines y rutinas, e instala el parche en la ROM.
* '''El parche''' ejecuta los sistemas durante el juego: administra el espacio disponible, prepara las transferencias y actualiza lo que se muestra en pantalla.

La consola no lee los archivos DynamicInfo, DrawInfo o PaletteEffect originales. Al instalar, la herramienta los convierte en datos y código que el juego puede utilizar directamente.

=== Qué prepara la instalación ===

Los recursos gráficos y las paletas se guardan en la ROM. La herramienta genera tablas para localizar sus datos y consultar información como el tamaño de una pose o la rutina que debe dibujarla.

Los DrawInfo también permiten generar rutinas de dibujo adaptadas a las características de cada grupo de poses. Así no es necesario interpretar el archivo de texto ni comprobar todas sus opciones durante cada frame.

Los nombres publicados en <code>DXDefines.asm</code> permiten que sprites, bloques y códigos UberASM encuentren esos recursos y las rutinas del sistema. Una reinstalación puede cambiar sus IDs o direcciones; por eso después hay que volver a insertar los recursos que dependen de ellos.

=== Dónde se guarda cada cosa ===

{| class="wikitable"
! Memoria !! Qué contiene
|-
| ROM || Código del juego y recursos instalados: gráficos, paletas, tablas y rutinas de dibujo.
|-
| RAM || Estado del sistema durante el juego: poses cargadas, asignaciones de paletas, temporizadores, colores preparados y listas de transferencias.
|-
| VRAM || Gráficos y mapas de tiles que utiliza la consola para construir la imagen.
|-
| CGRAM || Colores de las paletas.
|-
| OAM || Datos de dibujo de los sprites: posición, tile, paleta, tamaño y propiedades de sus piezas.
|}

Cargar una pose y dibujarla son trabajos distintos. Cargarla coloca sus gráficos en VRAM; dibujarla indica qué tiles utilizar y dónde mostrarlos. Del mismo modo, cargar una paleta cambia sus colores, pero no decide por sí solo qué sprite la utiliza.

== Recorrido de un frame ==

Durante el juego, los sprites y otros códigos deciden qué necesitan mostrar. Dynamic Xtreme prepara las cargas solicitadas y utiliza NMI para realizar las transferencias a la memoria de video.

Este es el recorrido general en un modo de juego donde el sistema está habilitado:

# NMI realiza las transferencias que se habían preparado y deja las listas disponibles para nuevas solicitudes.
# Se ejecuta la lógica del modo de juego: jugador, sprites, animaciones y otros códigos.
# Los recursos solicitan poses, paletas o transferencias y preparan sus datos de dibujo.
# La parte de paletas del game mode actualiza su estado y procesa los efectos globales que correspondan.
# En la siguiente oportunidad de NMI, se realizan las transferencias preparadas.

No todo ocurre dentro de una única rutina. Dynamic Xtreme interviene en distintos puntos del juego para que el trabajo de preparación no tenga que hacerse durante las transferencias.

== NMI y las transferencias de pantalla ==

NMI es una interrupción que SNES puede generar al comenzar el intervalo de VBlank, cuando termina de dibujar la parte visible del frame. El juego aprovecha ese momento para actualizar gráficos, colores y otros datos de pantalla.

Ese tiempo es limitado. La consola todavía tiene que realizar las tareas normales del juego, por lo que no se puede dedicar todo el intervalo a cargar poses dinámicas.

=== Preparar una carga no es ejecutarla ===

Cuando un código solicita una transferencia, normalmente no escribe los gráficos o colores en la memoria de video en ese mismo momento. Guarda una descripción de la carga en una lista de RAM.

Cada entrada contiene los datos necesarios para realizarla:

* Dirección y banco del origen.
* Cantidad de bytes.
* Destino en VRAM o CGRAM.

Durante NMI, el parche lee esas entradas y utiliza DMA para copiar los datos. DMA es el mecanismo de la consola que realiza la transferencia sin necesitar un bucle de instrucciones para copiar cada byte.

Una vez procesada la lista, sus entradas dejan de estar pendientes. Esto no borra los gráficos o colores que ya se copiaron: permanecen en su destino hasta que otro código los cambie.

Si el origen está en RAM, sus datos deben seguir siendo válidos hasta que se ejecute la transferencia.

=== Qué hace la rutina de Dynamic Xtreme ===

En un game mode permitido, la rutina de NMI de Dynamic Xtreme reinicia el contador de datos del nuevo frame, actualiza sus relojes y realiza las transferencias de gráficos y paletas que estén pendientes.

La lista de VRAM utiliza 0 para indicar que está vacía. La de CGRAM utiliza <code>$FF</code>; su contador representa el índice de la última entrada, no la cantidad de entradas.

Las listas se recorren desde la última entrada hacia la primera. Si varios códigos escriben sobre el mismo destino, deben coordinarse: no conviene depender del orden de solicitudes para decidir qué recurso debe quedarse allí.

El sistema no convierte todo el trabajo del juego en transferencias propias. Por ejemplo, el dibujo prepara datos OAM, y la actualización de OAM forma parte del flujo de pantalla del juego.

=== Presupuesto de datos por frame ===

<code>DX_Dynamic_CurrentDataSend</code> registra los bytes que las cargas del sistema han comprometido para el frame. <code>DX_Dynamic_MaxDataPerFrame</code> fija el límite que comprueban las solicitudes normales.

El límite predeterminado es <code>$0800</code>, es decir, 2048 bytes. Es una medida para controlar el trabajo de las transferencias; no significa que cualquier combinación de 2048 bytes tenga exactamente el mismo coste.

Cuando una solicitud no cabe, puede rechazarse para intentarla después. Ese rechazo no queda automáticamente guardado en una lista de espera para otro frame: el código que la necesita debe volver a solicitarla.

Las transferencias <code>Forced</code> omiten la comprobación del límite, pero también suman sus bytes al contador. No hacen que la consola tenga más tiempo; permiten dar prioridad a cargas que no deben quedar sujetas a esa comprobación.

== Game modes e inicialización ==

SMW utiliza game modes para separar estados como la carga del nivel, el juego dentro de un nivel y las pantallas de transición. El modo actual se guarda en <code>$0100</code>.

Dynamic Xtreme consulta una tabla para decidir en cuáles debe funcionar. No todos los modos necesitan mantener una caché de poses o preparar cargas dinámicas.

=== Modos permitidos y reinicio del sistema ===

En los modos no permitidos, la parte de game mode reinicializa el estado de Dynamic Xtreme. Así no se arrastran asignaciones o referencias que pertenecían a otra pantalla.

La inicialización prepara las listas de transferencias, los contadores y el estado de los sistemas habilitados. También establece valores iniciales como el presupuesto de datos por frame y las marcas que indican que todavía no hay una asignación válida.

Mientras el juego permanezca en un modo no permitido, ese reinicio puede repetirse. No depende únicamente de detectar que cambió el número de game mode.

Algunas llamadas tienen comprobaciones más restrictivas que la tabla general. Que Dynamic Xtreme esté activo en una pantalla no significa que todas las rutinas de sprites deban solicitar nuevas poses allí.

=== Trabajo durante el game mode ===

La parte de game mode integra las tareas que no necesitan ejecutarse dentro de NMI. Según las funcionalidades habilitadas, incluye el procesamiento del control, la preparación de actualizaciones de VRAM y el mantenimiento y procesamiento de paletas.

Después de la ejecución del modo de juego, el sistema de paletas limpia las marcas de actualización del frame y reduce los temporizadores que protegen sus asignaciones, cuando corresponde. El procesamiento de efectos globales también se realiza en esta parte, no durante la copia de cada color en NMI.

=== Dos relojes distintos ===

* <code>DX_Timer</code> avanza cuando se ejecuta la rutina correspondiente de NMI, incluso durante la pausa. Se utiliza, entre otras cosas, para saber cuánto tiempo lleva una pose sin utilizarse.
* <code>DX_SyncTimer</code> no avanza cuando el juego está pausado o la acción está congelada. Sirve para coordinar animaciones que deban detenerse junto con el juego.

Por eso una pose puede acumular tiempo sin uso durante la pausa, aunque una animación basada en <code>DX_SyncTimer</code> permanezca detenida.

== Carga de gráficos: GraphicsChange ==

<code>GraphicsChange</code> proporciona la base para programar transferencias a VRAM. La utilizan tanto las animaciones de tiles como los sistemas del jugador, Yoshi y poses dinámicas.

Una transferencia indica de dónde vienen los gráficos, cuánto ocupan y dónde deben colocarse. La macro comprueba el presupuesto, añade la entrada a la lista y actualiza el contador de datos si se acepta la carga.

Este sistema de carga no decide qué imagen debe seguir en una animación ni qué región de VRAM pertenece a cada recurso. Esas decisiones corresponden al código que solicita la transferencia o, en el caso de las poses dinámicas, a su administrador de espacio.

=== Animaciones sobre un destino fijo ===

Una animación de tiles puede copiar distintas imágenes al mismo destino. Los tiles del nivel siguen utilizando los mismos números, pero los gráficos que hay en esas posiciones van cambiando.

El código de animación elige el origen de cada paso y solicita la carga. Si la transferencia se rechaza, puede conservar el paso anterior y volver a intentarlo sin avanzar su estado.

Esto permite que las animaciones compartan el presupuesto con otros recursos dinámicos en lugar de realizar cargas sin tener en cuenta el trabajo ya solicitado.

=== Gráficos de poses dinámicas ===

Una pose no siempre se puede copiar como un bloque único de bytes a VRAM. El formato de tiles del sprite puede requerir repartir sus datos entre distintas filas.

La instalación prepara la información necesaria para esas cargas. Durante el juego, <code>DynamicRoutine</code> calcula los destinos a partir del lugar asignado a la pose y genera las entradas de transferencia correspondientes.

La decisión de cargar una pose y encontrarle espacio ocurre antes de ese paso. <code>DynamicRoutine</code> prepara la copia de sus gráficos; no realiza por sí sola toda la administración de la caché.

== Carga y asignación de paletas: PalettesChange ==

Una paleta instalada y una paleta de pantalla no son lo mismo. La primera es un conjunto de colores guardados en ROM; la segunda es un lugar de CGRAM donde esos colores pueden utilizarse para dibujar.

Por ejemplo, un sprite puede solicitar los colores de su paleta azul sin exigir que se coloquen siempre en la paleta 9. La asignación automática elige un destino disponible entre las paletas de sprites permitidas.

=== Carga directa de colores ===

Las transferencias a CGRAM se preparan en una lista, de forma similar a las cargas de gráficos. El destino se expresa como número de color y el tamaño como cantidad de bytes; cada color de SNES ocupa dos bytes.

Las macros <code>TransferPalette</code> también mantienen las copias de colores que necesitan SMW y Dynamic Xtreme. No basta con cambiar CGRAM: otras rutinas, como la animación de victoria del goal, pueden volver a utilizar los colores guardados por el juego.

Si la paleta va a recibir un efecto global, la macro prepara sus colores originales para que se aplique el efecto antes de mostrarlos. La carga del resultado se realiza después mediante el sistema de efectos.

=== Asignación automática ===

El administrador guarda qué ID de paleta ocupa cada destino y cuánto tiempo debe permanecer protegido. Para asignar una paleta, busca primero si ya existe una asignación con los mismos colores identificados por su ID y una condición de efecto compatible.

Si existe, puede compartir ese destino. Si no existe, busca un lugar libre y, después, uno que pueda reemplazarse porque dejó de estar protegido.

Esto evita cargar varias copias de una misma paleta para distintos sprites que pueden compartirla.

En las tablas de asignación, <code>$FFFF</code> identifica una entrada libre y <code>$FFFE</code> una entrada reservada que la asignación automática no debe reemplazar.

=== Protección mientras se utiliza ===

Cuando un recurso utiliza una paleta, su temporizador de protección se mantiene en 2. Mientras continúe solicitándola, otros recursos no deben reemplazarla automáticamente.

Que el temporizador llegue a cero no borra los colores ni elimina inmediatamente su ID. La asignación puede seguir reutilizándose si se solicita la misma paleta antes de que otro recurso la reemplace.

Los destinos manuales permiten elegir dónde colocar la paleta, y el modo manual sin carga permite utilizar colores que ya estaban preparados. Elegir el mismo destino para dos recursos con colores distintos sigue siendo responsabilidad de esos recursos.

=== Versión y cambios de paleta ===

En las rutinas de sprites, la versión selecciona una entrada de la lista de paletas del DynamicInfo. El sistema guarda también la última versión procesada para detectar si debe cambiar la selección.

No es necesario volver a cargar los colores cada frame si la selección sigue siendo válida. Mantener la protección de una paleta no significa que sus colores se hayan transferido otra vez.

== Dibujo de poses: DrawingSystem ==

El sistema de dibujo recibe una pose y la información necesaria para situarla en pantalla. A partir de los datos generados desde el DrawInfo, prepara las entradas OAM de sus tiles.

=== Rutinas generadas durante la instalación ===

La herramienta analiza qué tablas utiliza cada pose: tiles, posiciones, tamaños, propiedades y desplazamientos para los volteos.

Las poses con características compatibles pueden compartir una misma rutina de dibujo, aunque mantengan sus propios IDs y datos. La rutina generada incluye el tratamiento que necesita ese grupo, en lugar de interpretar todas las posibilidades del formato durante cada llamada.

=== Preparación de los tiles ===

El dibujo combina la posición del recurso con los desplazamientos de cada tile, aplica los volteos y prepara el número de tile y sus propiedades.

En una pose dinámica, los números de tile se ajustan al lugar donde quedaron cargados sus gráficos. En una pose estática se utilizan sus posiciones fijas. Si la pose toma un tile común desde <code>!Tile</code>, el código que la dibuja debe preparar ese valor.

También se comprueba si los tiles pueden verse en pantalla y si quedan entradas OAM disponibles. Los tiles descartados no generan un dibujo visible, aunque la pose tenga sus gráficos en VRAM.

=== Prioridad y espacio de OAM ===

Dynamic Xtreme organiza el espacio OAM teniendo en cuenta la prioridad de dibujo. En LoROM utiliza su propio seguimiento de entradas disponibles; en SA-1 aprovecha la integración con MaxTile.

La prioridad de dibujo ayuda a decidir el orden de las piezas de sprites. No debe confundirse con la propiedad que determina cómo se combinan con las capas del fondo.

El sistema no elimina los límites de sprites y tiles que SNES puede mostrar en una misma línea de pantalla.

== Jugador y Yoshi ==

=== PlayerFeatures ===

SMW utiliza rutinas específicas para elegir y cargar las piezas gráficas del jugador. <code>PlayerFeatures</code> integra esas cargas con Dynamic Xtreme y permite cambiar su origen de gráficos y paletas.

Para gráficos con la organización original, la rutina calcula las direcciones de las piezas que necesita la pose actual. Compara sus orígenes con los anteriores y prepara las cargas de las piezas que hayan cambiado.

Estas cargas utilizan transferencias forzadas. Así mantienen su prioridad, y los bytes que ocupan también cuentan para las solicitudes normales que se realizan después.

La paleta del jugador tiene un tratamiento especial y no se sustituye únicamente cambiando una paleta de sprite cualquiera. Su código combina la selección de colores del juego con el origen personalizado que se haya configurado.

El soporte para sistemas de jugador personalizados permite utilizar otras formas de administrar sus poses y dibujo; no convierte automáticamente un spritesheet arbitrario al formato del jugador original.

=== YoshiFeatures ===

<code>YoshiFeatures</code> permite cambiar el origen de los gráficos que utilizan las rutinas de Yoshi manteniendo la organización esperada de sus piezas.

Su código calcula las direcciones que necesita cada pieza y prepara sus transferencias a las posiciones correspondientes de VRAM. Como las cargas del jugador, estas actualizaciones tienen un tratamiento prioritario.

Esta funcionalidad depende de <code>PlayerFeatures</code>. Ambas intervienen en el manejo de gráficos del juego, por lo que las restricciones de compatibilidad del sistema del jugador también afectan al uso de Yoshi.

== Memoria y optimizaciones ==

=== Free7E2000 ===

SMW conserva en RAM gráficos originales que utiliza para el jugador, Yoshi y determinadas animaciones. En ROMs sin SA-1, <code>Free7E2000</code> adapta esas cargas para leer los datos correspondientes desde ROM.

El área recuperada se utiliza para las variables internas de Dynamic Xtreme. No se convierte en una zona libre que cualquier otro recurso pueda ocupar.

En SA-1, el sistema utiliza otras direcciones y esta opción se desactiva. Los rangos y la forma de reubicarlos están documentados en [[es/Dynamic_Xtreme#Espacios_de_RAM_utilizados|Compatibilidad: espacios de RAM utilizados]].

=== ControllerOptimization ===

El procesamiento del control que normalmente se ejecutaría desde NMI se realiza en la parte de game mode.

El propósito es dejar más tiempo disponible dentro de NMI, no añadir un frame de retraso al control ni cambiar los botones que recibe el juego.

=== FixedColorOptimization ===

El color fijo es un color que la consola puede utilizar para sus mezclas de color. Su actualización necesita preparar los componentes que se escriben en el registro correspondiente.

Esta optimización sustituye la rutina original por una secuencia más corta para realizar ese trabajo. El color sigue teniendo que enviarse a la consola; se reduce la preparación necesaria durante NMI.

=== KevinLMVRAMOptimization ===

Lunar Magic utiliza listas de actualizaciones llamadas stripe images para modificar partes de los mapas de tiles. Esas listas contienen tanto los datos como información sobre sus destinos.

La integración de la optimización de Kevin realiza fuera de NMI parte del procesamiento que adapta los destinos de esas actualizaciones. La transferencia de los datos de pantalla sigue necesitando ejecutarse en el momento correspondiente.

La opción integrada sustituye el uso del parche original por separado. Su restricción de desinstalación debe tenerse en cuenta antes de activarla.

=== StatusBarOptimization ===

La barra de estado original actualiza regiones concretas de VRAM. Esta optimización prepara de forma más directa las transferencias que necesita, reduciendo el trabajo de configuración de DMA durante NMI.

No reemplaza la barra por una nueva. Como modifica la rutina de actualización de la original, puede entrar en conflicto con recursos que la sustituyen, modifican o eliminan.

== Sistema de sprites dinámicos: DynamicPoses ==

El sistema de poses dinámicas trata el espacio disponible de VRAM como una caché compartida. Conserva poses que ya se cargaron para reutilizarlas y reemplaza las que han dejado de utilizarse cuando necesita espacio.

Un sprite no recibe necesariamente una región fija para todas sus poses. Solicita la pose que necesita y obtiene la referencia al lugar donde puede dibujarla.

=== Compartir una pose ===

Supongamos que varios sprites solicitan la misma pose. La primera solicitud puede necesitar cargar sus gráficos; las siguientes encuentran la misma pose registrada y utilizan su ubicación.

No hace falta cargar una copia por cada entidad. Cada una puede dibujarla en una posición distinta usando los mismos gráficos.

Esta reutilización se realiza por el ID de la pose. Que dos recursos distintos tengan gráficos visualmente iguales no significa, por sí solo, que sean la misma entrada de la caché.

=== Buscar una pose ya registrada ===

El sistema mantiene una tabla de búsqueda con el ID de cada pose registrada, su ubicación en VRAM y el momento en que se utilizó por última vez.

Para no recorrer siempre todas las poses, calcula un índice de búsqueda a partir del ID. La implementación utiliza una tabla hash de 128 entradas: el índice permite comenzar la búsqueda y el ID completo confirma si se encontró la pose correcta.

Si la pose ya está registrada, se actualiza su tiempo de último uso y se devuelve su referencia. No se prepara otra carga de gráficos.

=== Solicitar una pose nueva ===

Cuando la pose no está registrada, el recorrido general es:

# Consultar cuánto ocupan sus gráficos y cuántos bloques de VRAM necesita.
# Comprobar si sus bytes caben en el presupuesto del frame.
# Buscar un espacio adecuado que no esté reservado ni protegido.
# Retirar las referencias de las poses que deban reemplazarse en ese espacio.
# Registrar la nueva pose y su ubicación.
# Preparar las transferencias necesarias para colocar sus gráficos allí.

Si no hay presupuesto o espacio adecuado, la solicitud falla. No se completa parcialmente la asignación para obligar después al sprite a dibujar una pose que todavía no tiene preparada.

=== Mapa de espacio disponible ===

El mapa de VRAM distingue regiones reservadas, espacios libres y espacios ocupados por poses. Su unidad de reserva corresponde a bloques de gráficos de 16×16.

Las configuraciones de espacio indican qué partes de SP1-SP4 pueden utilizarse. El administrador no puede elegir una zona reservada para los gráficos fijos del nivel, el jugador u otro sistema.

Cada región conserva la información necesaria para conocer su comienzo y tamaño. Esto permite recorrer regiones completas en lugar de tratar cada tile como una asignación independiente.

Un espacio libre más grande puede dividirse al colocar una pose. También pueden considerarse regiones contiguas para obtener el espacio que necesita una solicitud.

=== Protección y elección de reemplazo ===

El tiempo desde el último uso indica cuándo puede reemplazarse una pose. Las utilizadas demasiado recientemente quedan protegidas: el administrador exige una antigüedad de al menos dos frames para considerar su espacio.

Entre las regiones utilizables, se favorecen las poses con mayor tiempo sin uso. Cuando la antigüedad es equivalente, se prefiere el espacio adecuado más pequeño para no consumir innecesariamente una región mayor.

Si una región contiene varias poses, no basta con que una de ellas sea antigua: la protección de las demás también cuenta al decidir si puede utilizarse todo ese espacio.

La protección no obliga a borrar una pose cuando deja de utilizarse. Puede permanecer registrada y reutilizarse más adelante sin una carga nueva, siempre que no haya sido reemplazada.

=== Qué ocurre si no se puede cambiar de pose ===

Las rutinas de carga para sprites pueden conservar la referencia a una pose anterior válida. Si una nueva solicitud falla, mantienen protegida esa pose anterior para que el sprite pueda continuar dibujándola.

Por eso hay que distinguir entre conseguir exactamente la pose nueva y disponer de una pose utilizable. El carry de una llamada con soporte para conservar la anterior puede indicar éxito aunque todavía no se haya cambiado a la pose solicitada.

Si nunca hubo una pose válida, no existe una anterior que se pueda mostrar. El código debe respetar ese resultado antes de dibujar.

=== Carga, dibujo y lógica del sprite ===

El administrador de poses no decide cómo se mueve o anima el personaje. El sprite elige su pose, solicita sus gráficos y utiliza el sistema de dibujo con el resultado disponible.

La comprobación de visibilidad permite evitar parte del trabajo gráfico cuando el sprite no necesita dibujarse. La short routine mantiene la lógica que corresponda; la long routine incluye el trabajo de paleta, pose y dibujo.

Mantener esas tareas separadas permite utilizar la misma infraestructura para sprites normales, cluster, extended y otros códigos.

== Efectos de paleta: PalettesEffects ==

El sistema de efectos transforma colores sin perder la referencia a los colores originales. Esto permite cambiar de efecto, combinar un efecto local con uno global o volver a la paleta sin efecto.

Los cálculos se realizan fuera de NMI. NMI recibe las transferencias con el resultado que debe mostrarse.

=== Colores originales y colores resultantes ===

El sistema distingue varias representaciones de una paleta:

{| class="wikitable"
! Datos !! Para qué se utilizan
|-
| Colores originales en formato SNES || Guardan la base que debe conservarse antes de aplicar el efecto global.
|-
| Base RGB || Separa rojo, verde y azul para los efectos que trabajan con esos componentes.
|-
| Base HSL || Separa tono, saturación y luminosidad para los efectos de ese tipo.
|-
| Colores resultantes en formato SNES || Contienen el resultado que puede copiarse a CGRAM.
|}

<code>DX_PPU_CGRAM_PaletteCopy</code> conserva la base en formato SNES. Las bases RGB y HSL utilizan tres bytes por color. El resultado preparado para pantalla utiliza dos bytes por color y se guarda en <code>DX_PPU_CGRAM_PaletteWriteMirror</code>, que corresponde al buffer de paletas del juego.

Los indicadores de base cargada permiten saber qué representaciones ya están preparadas. Cambiar de un efecto RGB a uno HSL no debe convertir el resultado afectado en los nuevos colores originales.

=== Preparar y reutilizar una base ===

Si una paleta no tiene todavía una base registrada, el sistema puede obtener sus colores del buffer del juego. Las cargas explícitas, como <code>TransferPalette</code>, proporcionan directamente los colores que deben servir de base.

La conversión a RGB o HSL se realiza cuando hace falta esa representación. Una vez preparada, puede reutilizarse mientras no cambien sus colores de origen.

Cuando se cargan colores nuevos, deben invalidarse las conversiones y los resultados anteriores que dependían de ellos. Las llamadas de carga correspondientes se encargan de ese mantenimiento.

=== Qué describe un efecto ===

Cada efecto instalado tiene un ID y datos que indican su tipo, los valores de sus canales y sus ratios.

Los canales RGB y HSL utilizan valores de 0 a 31. Los ratios utilizan 0 a 127: 0 conserva el origen y 127 aplica por completo el cambio indicado.

Los efectos de mezcla modifican uno o varios componentes. Los de transición utilizan otra paleta como destino. Durante la instalación, las paletas de destino se convierten al formato RGB o HSL que utilizará el efecto, evitando hacer esa conversión del destino en cada llamada.

=== Efecto global ===

El efecto global se selecciona con un ID compartido. Las máscaras de paletas indican cuáles deben recibirlo; el color fijo y el color 0,0 tienen sus propios indicadores de participación.

El administrador revisa si cada paleta necesita procesarse. Si conserva la misma base y el resultado del mismo efecto sigue siendo válido, no es necesario calcularlo otra vez.

Cuando cambia el ID global, se marcan como pendientes los resultados que dependían del efecto anterior. Las bases de color pueden seguir utilizándose si sus colores originales no cambiaron.

El ID global 0 permite volver a los colores de base. No equivale simplemente a dejar de procesar las paletas: el sistema debe preparar la restauración de las que estaban afectadas.

=== Efectos locales y concatenación ===

Un efecto local permite modificar la paleta de un recurso concreto. Si además debe recibir el efecto global, los dos cambios tienen que aplicarse en el orden previsto.

Las llamadas de concatenación permiten utilizar el resultado local como base del efecto global. Por ejemplo, un sprite puede recibir un cambio de tono propio y después el efecto de oscurecimiento del nivel.

La concatenación RGB se utiliza con efectos RGB; la HSL, con efectos HSL. Preparar una base local no implica que haya que cargar primero sus colores sin el efecto global.

Una paleta de CGRAM sigue siendo compartida por todos los recursos que la utilizan. Si dos sprites necesitan resultados locales distintos, no deben depender del mismo destino de paleta para mostrarlos simultáneamente.

=== Publicar el resultado ===

Después del cálculo, los colores se convierten al formato de SNES y se programa su transferencia. Esa solicitud también debe respetar el presupuesto correspondiente.

Preparar los colores originales o calcular un efecto no significa que el resultado ya se haya enviado a CGRAM. El administrador confirma el avance de sus estados según el resultado de la carga, y puede volver a intentar una actualización pendiente.

Cuando corresponde, las rutinas conservan el resultado anterior utilizable mientras el nuevo todavía no está disponible. Esto evita confundir una actualización pendiente con la ausencia total de una paleta que se pueda mostrar.

Enviar primero los colores originales directamente a CGRAM rompería esa separación: la paleta podría verse un frame sin efecto antes de mostrar el resultado correcto. Por eso las cargas destinadas al efecto global preparan la base sin publicar antes una versión sin efecto.

== Integración de los sistemas ==

El funcionamiento de un sprite dinámico reúne varios sistemas sin convertirlos en una sola tarea:

# Su lógica elige la pose y la variante de paleta que necesita.
# La asignación de paletas busca un destino utilizable y prepara los colores cuando hace falta.
# La caché busca la pose o encuentra espacio para cargarla.
# El dibujo utiliza la referencia disponible para preparar sus tiles en OAM.
# El administrador de efectos prepara los cambios globales pendientes sobre las paletas habilitadas.
# NMI realiza las transferencias de gráficos y colores que quedaron programadas.

Compartir gráficos, compartir colores y compartir una rutina de dibujo son optimizaciones distintas. Un recurso puede aprovechar una de ellas sin que eso implique que deba compartir todas las demás.

== Lecturas relacionadas ==

* [[es/Dynamic_Xtreme|Artículo principal]]: funcionalidades y compatibilidad.
* [[es/Dynamic_Xtreme_files_and_formats|Archivos y formatos]]: datos que utiliza la instalación.
* [[es/Dynamic_Xtreme_sprite_creation_guide|Creación de sprites dinámicos]]: aplicación práctica en un sprite.
* [[es/Dynamic_Xtreme_UberASM_guide|Dynamic Xtreme con UberASM]]: configuración y ejemplos de nivel.
* [[es/Dynamic_Xtreme_ASM_API|API ASM]]: parámetros y resultados de las llamadas.

es/Dynamic Xtreme

2026-10-25T00:59:13Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme}}

Dynamic Xtreme es una herramienta de soporte dinámico avanzada para Super Mario World en el SNES. Desarrollada para la comunidad de ROM hacking, permite realizar cambios gráficos y de paletas en tiempo real durante la ejecución del juego, ampliando considerablemente las capacidades técnicas originales del hardware del SNES.La herramienta se centra en ofrecer un sistema completo y flexible de gráficos dinámicos, con énfasis en el rendimiento y la modularidad.

Entre sus características principales se incluyen:
* Cambios gráficos y de paleta en tiempo real (on-the-fly).
* El sistema de Dynamic Sprite más potente y flexible disponible para Super Mario World.
* Advanced Drawing System, que permite dibujar cualquier frame registrado en pantalla con control total sobre prioridad, capa, desplazamiento (offset) y propiedades.
* Efectos de paleta avanzados, que incluyen modificación en tiempo real mediante tono (hue), saturación, brillo, fusión de colores, transiciones suaves y control individual de canales RGB y HSL.
* Reemplazo completo de gráficos y paletas del jugador, compatible con cualquier tamaño de Mario, cualquier cantidad de frames y cualquier estilo de animación.
* Soporte total para el reemplazo de gráficos de Yoshi.
* Optimizaciones intensivas en el NMI-handler para maximizar el rendimiento.

Las funciones de Dynamic Xtreme se seleccionan durante la instalación para utilizar solo las que necesita el proyecto. Algunas tienen dependencias, problemas de compatibilidad o restricciones para desinstalarlas; revisa las advertencias de cada opción. La herramienta fue creada con el objetivo de facilitar la implementación de efectos visuales complejos en hacks de Super Mario World manteniendo un alto nivel de compatibilidad y estabilidad.

== Objetivos del proyecto ==

El principal objetivo de Dynamic Xtreme es facilitar el uso de sprites dinámicos y ofrecer un soporte completo para cambios de gráficos, paletas y tilemaps en tiempo real.

El proyecto busca aprovechar al máximo el potencial del SNES sin requerir que el usuario tenga conocimientos avanzados sobre el hardware interno de la consola. Muchos sistemas dinámicos tradicionales suelen ser complejos y dependen fuertemente de conceptos técnicos como VRAM, CGRAM, OAM o DMA. Dynamic Xtreme intenta abstraer gran parte de esa complejidad mediante herramientas y formatos más modernos, legibles y fáciles de utilizar.

Otro de los objetivos principales del proyecto es mantener un alto rendimiento incluso en situaciones visualmente complejas, permitiendo el uso intensivo de gráficos dinámicos, efectos de paletas y sistemas avanzados de renderizado sin comprometer innecesariamente la performance.

Además, Dynamic Xtreme busca que los sprites dinámicos puedan utilizarse de una forma tan natural y sencilla como si fueran sprites normales. La idea es que las personas enfocadas en level design o creación de contenido no necesiten preocuparse constantemente por las limitaciones técnicas internas del sistema y puedan trabajar con recursos dinámicos de forma transparente y práctica.

== Funcionalidades ==

Durante la instalación puedes elegir qué funcionalidades habilitar. Los nombres entre paréntesis corresponden a las opciones del instalador y de <code>Settings.json</code>.

=== Gráficos, poses y paletas ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Cambios de gráficos (<code>GraphicsChange</code>) || Permite cargar gráficos durante el juego. Es la base para las animaciones de tiles, los cambios de gráficos del nivel y las poses dinámicas.
|-
| Cambios de paletas (<code>PalettesChange</code>) || Permite cargar y administrar paletas durante el juego. Incluye la asignación automática de paletas para que los sprites puedan compartir los mismos colores sin cargarlos varias veces.
|-
| Poses dinámicas (<code>DynamicPoses</code>) || Administra el espacio de VRAM como una caché de poses: reutiliza las que ya están cargadas, permite compartirlas entre entidades y elige cuáles reemplazar cuando hace falta espacio. Así evita cargas innecesarias.
|-
| Dibujo de poses (<code>DrawingSystem</code>) || Dibuja las poses definidas en archivos DrawInfo, tanto dinámicas como estáticas. Permite controlar sus tiles, posición, volteo, paleta y prioridad de dibujo.
|-
| Efectos de paleta (<code>PalettesEffects</code>) || Permite cambiar colores mediante efectos RGB y HSL: teñir paletas, modificar tono, saturación o luminosidad, y realizar transiciones entre paletas. Pueden aplicarse a recursos individuales o como un efecto global.
|}

La carga de poses dinámicas y el dibujo son sistemas separados: puedes dibujar una pose estática sin cargar sus gráficos dinámicamente.

=== Jugador y Yoshi ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Funciones del jugador (<code>PlayerFeatures</code>) || Permite cambiar los gráficos y paletas del jugador y adaptar su dibujo y carga de poses a sistemas personalizados. También permite ocultarlo o desactivar sus cargas dinámicas. Puede entrar en conflicto con parches que modifican los gráficos o paletas del jugador; revisa la advertencia del instalador antes de habilitarla.
|-
| Funciones de Yoshi (<code>YoshiFeatures</code>) || Permite cambiar los gráficos de Yoshi manteniendo la organización de sus poses originales. Requiere <code>PlayerFeatures</code> y comparte sus restricciones de compatibilidad.
|}

=== Memoria y optimizaciones ===

Estas opciones reorganizan parte del trabajo del juego para dejar más tiempo disponible para las cargas de gráficos y paletas. NMI es la rutina que realiza las actualizaciones de pantalla durante la pausa entre un frame y el siguiente.

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Liberar el área <code>$7E2000</code> (<code>Free7E2000</code>) || En ROMs sin SA-1, evita mantener en RAM ciertos gráficos originales del jugador, Yoshi y animaciones, y permite leerlos desde ROM. Dynamic Xtreme utiliza el espacio recuperado para sus variables internas; no queda libre para usarlo sin reservar. Esta opción no se aplica a ROMs con SA-1.
|-
| Optimización del control (<code>ControllerOptimization</code>) || Mueve el procesamiento del control fuera de NMI para dejar más tiempo disponible para las actualizaciones de pantalla.
|-
| Optimización del color fijo (<code>FixedColorOptimization</code>) || Reduce el trabajo de NMI relacionado con la actualización del color fijo que utiliza el juego para sus mezclas de color.
|-
| Optimización de VRAM de Lunar Magic de Kevin (<code>KevinLMVRAMOptimization</code>) || Integra la optimización de Kevin para las actualizaciones de VRAM de Lunar Magic y mueve parte de su procesamiento fuera de NMI. Utiliza esta versión en lugar del parche original por separado. Una vez instalada, no debe desinstalarse: hacerlo puede dañar el funcionamiento de la ROM.
|-
| Optimización de la barra de estado (<code>StatusBarOptimization</code>) || Reduce el trabajo de NMI de la barra de estado original. No es compatible con recursos que la reemplazan o modifican, como barras de estado personalizadas o parches que la eliminan.
|}

Para revisar qué opciones pueden entrar en conflicto con otros recursos y qué RAM utiliza el sistema, consulta [[#Compatibilidad|Compatibilidad]].

Algunas funcionalidades necesitan otras: <code>DynamicPoses</code> requiere <code>GraphicsChange</code>; <code>PalettesEffects</code> requiere <code>PalettesChange</code>; <code>PlayerFeatures</code> necesita ambas opciones de cambios gráficos y de paletas; y <code>YoshiFeatures</code> requiere <code>PlayerFeatures</code>.

== Quick Start ==

'''Guía rápida de instalación:''' [[es/Dynamic_Xtreme_Quick_Start|Quick Start]]

== Herramientas y Soporte ==

== Archivos y formatos ==

'''Artículo relacionado:''' [[es/Dynamic_Xtreme_files_and_formats|Archivos y Formatos de Dynamic Xtreme]]

== Guía de creación de sprites dinámicos ==

Para aprender a preparar, programar, cargar y dibujar un sprite dinámico, consulta la [[es/Dynamic_Xtreme_sprite_creation_guide|guía de creación de sprites dinámicos con Dynamic Xtreme]].

== Dynamic Xtreme con UberASM ==

La [[es/Dynamic_Xtreme_UberASM_guide|guía de Dynamic Xtreme con UberASM]] muestra cómo reservar paletas, configurar el espacio para sprites dinámicos y el límite de datos por frame, crear animaciones, cambiar gráficos del jugador y aplicar efectos de paleta.

== API ==

La [[es/Dynamic_Xtreme_ASM_API|referencia de la API ASM]] explica cómo utilizar las variables, los defines, las rutinas y las macros de Dynamic Xtreme. Incluye los datos que necesita cada llamada, sus resultados y ejemplos de uso para trabajar con poses, dibujo, paletas, efectos de color y transferencias de gráficos, además de las macros de multiplicación y división.

== Funcionamiento interno del sistema ==

== Compatibilidad ==

En general, las funcionalidades que no muestran warnings en el instalador no suelen presentar problemas de incompatibilidad con otros recursos. Estas son:

* <code>GraphicsChange</code>
* <code>PalettesChange</code>
* <code>DynamicPoses</code>
* <code>DrawingSystem</code>
* <code>PalettesEffects</code>
* <code>Free7E2000</code>
* <code>ControllerOptimization</code>
* <code>FixedColorOptimization</code>

Esto no garantiza que cualquier combinación de recursos funcione: dos códigos todavía pueden utilizar la misma RAM, el mismo espacio de VRAM o modificar la misma rutina del juego. Además, <code>YoshiFeatures</code> necesita <code>PlayerFeatures</code>, por lo que también debes considerar las restricciones de esta última.

=== Funcionalidades con restricciones de compatibilidad ===

{| class="wikitable"
! Funcionalidad opcional !! Posibles conflictos y qué hacer
|-
| <code>PlayerFeatures</code> || Puede entrar en conflicto con '''LX5's Powerups''', '''Player 8x8 tiles DMAer''', '''Player 32x32''' y otros sistemas que reemplazan la carga de gráficos o paletas del jugador. '''Player Revolution''' sí es compatible. Si tu sistema de jugador necesita esas rutinas originales, deja esta opción deshabilitada; también tendrás que deshabilitar <code>YoshiFeatures</code>.
|-
| <code>YoshiFeatures</code> || Depende de <code>PlayerFeatures</code> y hereda sus restricciones de compatibilidad, aunque no muestre un warning propio. Si otro recurso es incompatible con <code>PlayerFeatures</code>, no puedes evitar ese conflicto habilitando únicamente <code>YoshiFeatures</code>: debes dejar ambas deshabilitadas.
|-
| <code>StatusBarOptimization</code> || No es compatible con recursos que modifican, reemplazan o eliminan la barra de estado original, como '''LX5's DKC Style Status Bar''', '''Minimalistic Status Bar''' y '''Nuke Status Bar'''. Si utilizas uno de ellos, deja esta optimización deshabilitada.
|-
| <code>KevinLMVRAMOptimization</code> || Integra el parche de optimización de VRAM de Lunar Magic de Kevin: utiliza esta versión en lugar del parche original por separado. Su warning también indica que '''no debe desinstalarse después de instalarla''', porque hacerlo puede romper el funcionamiento de la ROM. Si necesitas revertirla, restaura una copia de seguridad anterior a su instalación.
|}

Estas funcionalidades son opcionales: puedes dejar deshabilitada la que entra en conflicto y seguir utilizando los demás sistemas de Dynamic Xtreme, respetando sus dependencias. Deshabilitar una opción no deshace los cambios de otro parche ni elimina la restricción de desinstalación de <code>KevinLMVRAMOptimization</code>.

=== Espacios de RAM utilizados ===

Las direcciones principales se configuran en <code>ASM/DXDefines.asm</code>, dentro de la carpeta de Dynamic Xtreme. En el repositorio, ese archivo corresponde a <code>DynamicXtremeLibrary/ASM/DXDefines.asm</code>.

El espacio utilizado depende de las funcionalidades habilitadas y de si la ROM utiliza SA-1. Los siguientes rangos incluyen el primer y el último byte y están calculados con '''todas las funcionalidades que reservan RAM habilitadas''', <code>!VRAMTransferSize = 64</code> y <code>!CGRAMTransferSize = 64</code>:

{| class="wikitable"
! Configuración !! Bloque <code>!Variables</code> !! Tamaño !! Bloque <code>!Variables2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2000–$7E2500</code> || <code>$0501</code>: 1281 bytes || <code>$7E2800–$7E3608</code> || <code>$0E09</code>: 3593 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB440–$7FB940</code> || <code>$0501</code>: 1281 bytes || <code>$7F9C80–$7FAA88</code> || <code>$0E09</code>: 3593 bytes
|-
| SA-1 || <code>$40C000–$40C47E</code> || <code>$047F</code>: 1151 bytes || <code>$418AFF–$419907</code> || <code>$0E09</code>: 3593 bytes
|}

Los dos bloques internos suman '''4874 bytes en LoROM''' y '''4744 bytes en SA-1'''. La diferencia se debe a los 130 bytes del sistema de dibujo que solo se reservan en LoROM. No se ocupa automáticamente el espacio que queda entre los bloques.

Al deshabilitar una funcionalidad se eliminan sus reservas condicionales y cambian las direcciones posteriores. Aumentar <code>!VRAMTransferSize</code> o <code>!CGRAMTransferSize</code> también aumenta el tamaño de sus tablas.

==== Tablas utilizadas por los sprites ====

<code>DX_FreeRams</code> y <code>DX_FreeRams2</code> '''no son espacios disponibles para escribir variables propias''': a partir de esas posiciones se ubican las tablas de sprites de <code>DynamicXSpritesTables.asm</code> y <code>MoreSpriteMiscs.asm</code>. También debes reservarlas si utilizas esos recursos.

Con la misma configuración de la tabla anterior, sus rangos son:

{| class="wikitable"
! Configuración !! Tablas desde <code>DX_FreeRams</code> !! Tamaño !! Tablas desde <code>DX_FreeRams2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2501–$7E26EC</code> || 492 bytes || <code>$7E3609–$7E3824</code> || 540 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB941–$7FBB2C</code> || 492 bytes || <code>$7FAC82–$7FAE9D</code> || 540 bytes
|-
| SA-1 || <code>$40C47F–$40C6D8</code> || 602 bytes || <code>$419908–$419BCD</code> || 710 bytes
|}

Incluyendo estas tablas, el espacio descrito suma '''5906 bytes en LoROM''' y '''6056 bytes en SA-1'''. Las tablas se calculan para 12 sprites normales en LoROM y 22 en SA-1, además de los slots de cluster, extended y smoke correspondientes.

Normalmente, <code>DX_FreeRams2</code> comienza justo después del segundo bloque interno. En LoROM sin <code>Free7E2000</code> se coloca por separado mediante <code>!Variables3 = $7FAC82</code>; por eso sus tablas no empiezan inmediatamente después de <code>!Variables2</code>.

Dynamic Xtreme también utiliza los espejos existentes del color fijo y de la paleta: <code>$7E0701</code> (2 bytes) y <code>$7E0703</code> (512 bytes) en LoROM. En SA-1 sus direcciones declaradas son <code>$406701</code> y <code>$006703</code>. No son reservas adicionales dentro de los bloques anteriores ni direcciones libres para tus códigos.

==== Reubicar la RAM si hay un conflicto ====

Si otro recurso utiliza alguno de estos espacios, puedes modificar '''<code>ASM/DXDefines.asm</code>''' para hacer que Dynamic Xtreme utilice otras zonas disponibles de tu romhack.

* Cambia <code>!Variables</code> y <code>!Variables2</code> en la configuración correspondiente a tu ROM: LoROM con <code>Free7E2000</code>, LoROM sin esa opción o SA-1.
* En LoROM sin <code>Free7E2000</code>, revisa también <code>!Variables3</code>, que determina dónde empiezan las tablas de <code>DX_FreeRams2</code>.
* Reserva espacio suficiente para el bloque completo y las tablas de sprites que le siguen. No basta con que la primera dirección esté libre.
* Respeta el mapa de memoria y los bancos que necesitan las rutinas. No cualquier dirección libre sirve para cualquier acceso.
* Después de cambiar las direcciones, reinstala Dynamic Xtreme y vuelve a insertar PIXI, UberASM y los demás recursos que utilicen sus defines.

Con <code>Free7E2000</code>, Dynamic Xtreme aprovecha el área de RAM que recupera al reubicar los gráficos originales; no la compartas con otros recursos sin comprobar qué parte utiliza. Sin esa opción, las direcciones alternativas pueden coincidir con las de otros recursos habituales. SA-1 utiliza sus propias direcciones y desactiva <code>Free7E2000</code>.

Modifica el archivo de la carpeta '''ASM''', no las copias generadas en <code>ExtraDefines</code> o <code>Patch/ExtraDefines</code>: esas copias se regeneran durante la instalación.

== Recursos hechos con Dynamic Xtreme ==

La mayoría de los recursos desarrollados para Dynamic Xtreme no suelen publicarse en sitios tradicionales como SMW Central debido a que muchos de ellos dependen directamente del framework y sus sistemas avanzados.

En su lugar, los recursos, ejemplos, sistemas y proyectos relacionados con Dynamic Xtreme se encuentran recopilados principalmente en:

https://snestorage.dev

Allí es posible encontrar sprites, sistemas de jugador, efectos gráficos, ejemplos técnicos y otros recursos diseñados específicamente para trabajar con Dynamic Xtreme.

== Conclusión ==

Dynamic Xtreme es un proyecto orientado a modernizar y simplificar el uso de sistemas dinámicos en Super Mario World, ofreciendo herramientas más flexibles, potentes y fáciles de utilizar sin perder compatibilidad ni control avanzado.

El proyecto continúa evolucionando constantemente con nuevas optimizaciones, formatos y herramientas orientadas tanto a usuarios avanzados como a personas que recién comienzan a trabajar con gráficos dinámicos en SNES.

La intención principal de Dynamic Xtreme es permitir la creación de recursos y sistemas cada vez más complejos, manteniendo al mismo tiempo un workflow más limpio, mantenible y accesible para la comunidad.

es/Dynamic Xtreme

2026-10-25T00:57:19Z

Anonimzwx:

{{Select Language|Dynamic_Xtreme}}

Dynamic Xtreme es una herramienta de soporte dinámico avanzada para Super Mario World en el SNES. Desarrollada para la comunidad de ROM hacking, permite realizar cambios gráficos y de paletas en tiempo real durante la ejecución del juego, ampliando considerablemente las capacidades técnicas originales del hardware del SNES.La herramienta se centra en ofrecer un sistema completo y flexible de gráficos dinámicos, con énfasis en el rendimiento y la modularidad.

Entre sus características principales se incluyen:
* Cambios gráficos y de paleta en tiempo real (on-the-fly).
* El sistema de Dynamic Sprite más potente y flexible disponible para Super Mario World.
* Advanced Drawing System, que permite dibujar cualquier frame registrado en pantalla con control total sobre prioridad, capa, desplazamiento (offset) y propiedades.
* Efectos de paleta avanzados, que incluyen modificación en tiempo real mediante tono (hue), saturación, brillo, fusión de colores, transiciones suaves y control individual de canales RGB y HSL.
* Reemplazo completo de gráficos y paletas del jugador, compatible con cualquier tamaño de Mario, cualquier cantidad de frames y cualquier estilo de animación.
* Soporte total para el reemplazo de gráficos de Yoshi.
* Optimizaciones intensivas en el NMI-handler para maximizar el rendimiento.

Las funciones de Dynamic Xtreme se seleccionan durante la instalación para utilizar solo las que necesita el proyecto. Algunas tienen dependencias, problemas de compatibilidad o restricciones para desinstalarlas; revisa las advertencias de cada opción. La herramienta fue creada con el objetivo de facilitar la implementación de efectos visuales complejos en hacks de Super Mario World manteniendo un alto nivel de compatibilidad y estabilidad.

== Objetivos del proyecto ==

El principal objetivo de Dynamic Xtreme es facilitar el uso de sprites dinámicos y ofrecer un soporte completo para cambios de gráficos, paletas y tilemaps en tiempo real.

El proyecto busca aprovechar al máximo el potencial del SNES sin requerir que el usuario tenga conocimientos avanzados sobre el hardware interno de la consola. Muchos sistemas dinámicos tradicionales suelen ser complejos y dependen fuertemente de conceptos técnicos como VRAM, CGRAM, OAM o DMA. Dynamic Xtreme intenta abstraer gran parte de esa complejidad mediante herramientas y formatos más modernos, legibles y fáciles de utilizar.

Otro de los objetivos principales del proyecto es mantener un alto rendimiento incluso en situaciones visualmente complejas, permitiendo el uso intensivo de gráficos dinámicos, efectos de paletas y sistemas avanzados de renderizado sin comprometer innecesariamente la performance.

Además, Dynamic Xtreme busca que los sprites dinámicos puedan utilizarse de una forma tan natural y sencilla como si fueran sprites normales. La idea es que las personas enfocadas en level design o creación de contenido no necesiten preocuparse constantemente por las limitaciones técnicas internas del sistema y puedan trabajar con recursos dinámicos de forma transparente y práctica.

== Funcionalidades ==

Durante la instalación puedes elegir qué funcionalidades habilitar. Los nombres entre paréntesis corresponden a las opciones del instalador y de <code>Settings.json</code>.

=== Gráficos, poses y paletas ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Cambios de gráficos (<code>GraphicsChange</code>) || Permite cargar gráficos durante el juego. Es la base para las animaciones de tiles, los cambios de gráficos del nivel y las poses dinámicas.
|-
| Cambios de paletas (<code>PalettesChange</code>) || Permite cargar y administrar paletas durante el juego. Incluye la asignación automática de paletas para que los sprites puedan compartir los mismos colores sin cargarlos varias veces.
|-
| Poses dinámicas (<code>DynamicPoses</code>) || Administra el espacio de VRAM como una caché de poses: reutiliza las que ya están cargadas, permite compartirlas entre entidades y elige cuáles reemplazar cuando hace falta espacio. Así evita cargas innecesarias.
|-
| Dibujo de poses (<code>DrawingSystem</code>) || Dibuja las poses definidas en archivos DrawInfo, tanto dinámicas como estáticas. Permite controlar sus tiles, posición, volteo, paleta y prioridad de dibujo.
|-
| Efectos de paleta (<code>PalettesEffects</code>) || Permite cambiar colores mediante efectos RGB y HSL: teñir paletas, modificar tono, saturación o luminosidad, y realizar transiciones entre paletas. Pueden aplicarse a recursos individuales o como un efecto global.
|}

La carga de poses dinámicas y el dibujo son sistemas separados: puedes dibujar una pose estática sin cargar sus gráficos dinámicamente.

=== Jugador y Yoshi ===

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Funciones del jugador (<code>PlayerFeatures</code>) || Permite cambiar los gráficos y paletas del jugador y adaptar su dibujo y carga de poses a sistemas personalizados. También permite ocultarlo o desactivar sus cargas dinámicas. Puede entrar en conflicto con parches que modifican los gráficos o paletas del jugador; revisa la advertencia del instalador antes de habilitarla.
|-
| Funciones de Yoshi (<code>YoshiFeatures</code>) || Permite cambiar los gráficos de Yoshi manteniendo la organización de sus poses originales. Requiere las funciones del jugador.
|}

=== Memoria y optimizaciones ===

Estas opciones reorganizan parte del trabajo del juego para dejar más tiempo disponible para las cargas de gráficos y paletas. NMI es la rutina que realiza las actualizaciones de pantalla durante la pausa entre un frame y el siguiente.

{| class="wikitable"
! Funcionalidad !! Para qué sirve
|-
| Liberar el área <code>$7E2000</code> (<code>Free7E2000</code>) || En ROMs sin SA-1, evita mantener en RAM ciertos gráficos originales del jugador, Yoshi y animaciones, y permite leerlos desde ROM. Dynamic Xtreme utiliza el espacio recuperado para sus variables internas; no queda libre para usarlo sin reservar. Esta opción no se aplica a ROMs con SA-1.
|-
| Optimización del control (<code>ControllerOptimization</code>) || Mueve el procesamiento del control fuera de NMI para dejar más tiempo disponible para las actualizaciones de pantalla.
|-
| Optimización del color fijo (<code>FixedColorOptimization</code>) || Reduce el trabajo de NMI relacionado con la actualización del color fijo que utiliza el juego para sus mezclas de color.
|-
| Optimización de VRAM de Lunar Magic de Kevin (<code>KevinLMVRAMOptimization</code>) || Integra la optimización de Kevin para las actualizaciones de VRAM de Lunar Magic y mueve parte de su procesamiento fuera de NMI. Utiliza esta versión en lugar del parche original por separado. Una vez instalada, no debe desinstalarse: hacerlo puede dañar el funcionamiento de la ROM.
|-
| Optimización de la barra de estado (<code>StatusBarOptimization</code>) || Reduce el trabajo de NMI de la barra de estado original. No es compatible con recursos que la reemplazan o modifican, como barras de estado personalizadas o parches que la eliminan.
|}

Para revisar qué opciones pueden entrar en conflicto con otros recursos y qué RAM utiliza el sistema, consulta [[#Compatibilidad|Compatibilidad]].

Algunas funcionalidades necesitan otras: <code>DynamicPoses</code> requiere <code>GraphicsChange</code>; <code>PalettesEffects</code> requiere <code>PalettesChange</code>; <code>PlayerFeatures</code> necesita ambas opciones de cambios gráficos y de paletas; y <code>YoshiFeatures</code> requiere <code>PlayerFeatures</code>.

== Quick Start ==

'''Guía rápida de instalación:''' [[es/Dynamic_Xtreme_Quick_Start|Quick Start]]

== Herramientas y Soporte ==

== Archivos y formatos ==

'''Artículo relacionado:''' [[es/Dynamic_Xtreme_files_and_formats|Archivos y Formatos de Dynamic Xtreme]]

== Guía de creación de sprites dinámicos ==

Para aprender a preparar, programar, cargar y dibujar un sprite dinámico, consulta la [[es/Dynamic_Xtreme_sprite_creation_guide|guía de creación de sprites dinámicos con Dynamic Xtreme]].

== Dynamic Xtreme con UberASM ==

La [[es/Dynamic_Xtreme_UberASM_guide|guía de Dynamic Xtreme con UberASM]] muestra cómo reservar paletas, configurar el espacio para sprites dinámicos y el límite de datos por frame, crear animaciones, cambiar gráficos del jugador y aplicar efectos de paleta.

== API ==

La [[es/Dynamic_Xtreme_ASM_API|referencia de la API ASM]] explica cómo utilizar las variables, los defines, las rutinas y las macros de Dynamic Xtreme. Incluye los datos que necesita cada llamada, sus resultados y ejemplos de uso para trabajar con poses, dibujo, paletas, efectos de color y transferencias de gráficos, además de las macros de multiplicación y división.

== Funcionamiento interno del sistema ==

== Compatibilidad ==

En general, las funcionalidades que no muestran warnings en el instalador no suelen presentar problemas de incompatibilidad con otros recursos. Estas son:

* <code>GraphicsChange</code>
* <code>PalettesChange</code>
* <code>DynamicPoses</code>
* <code>DrawingSystem</code>
* <code>PalettesEffects</code>
* <code>Free7E2000</code>
* <code>ControllerOptimization</code>
* <code>FixedColorOptimization</code>
* <code>YoshiFeatures</code>

Esto no garantiza que cualquier combinación de recursos funcione: dos códigos todavía pueden utilizar la misma RAM, el mismo espacio de VRAM o modificar la misma rutina del juego. Además, <code>YoshiFeatures</code> necesita <code>PlayerFeatures</code>, por lo que también debes considerar las restricciones de esta última.

=== Funcionalidades con advertencias ===

{| class="wikitable"
! Funcionalidad opcional !! Posibles conflictos y qué hacer
|-
| <code>PlayerFeatures</code> || Puede entrar en conflicto con '''LX5's Powerups''', '''Player 8x8 tiles DMAer''', '''Player 32x32''' y otros sistemas que reemplazan la carga de gráficos o paletas del jugador. '''Player Revolution''' sí es compatible. Si tu sistema de jugador necesita esas rutinas originales, deja esta opción deshabilitada; también tendrás que deshabilitar <code>YoshiFeatures</code>.
|-
| <code>StatusBarOptimization</code> || No es compatible con recursos que modifican, reemplazan o eliminan la barra de estado original, como '''LX5's DKC Style Status Bar''', '''Minimalistic Status Bar''' y '''Nuke Status Bar'''. Si utilizas uno de ellos, deja esta optimización deshabilitada.
|-
| <code>KevinLMVRAMOptimization</code> || Integra el parche de optimización de VRAM de Lunar Magic de Kevin: utiliza esta versión en lugar del parche original por separado. Su warning también indica que '''no debe desinstalarse después de instalarla''', porque hacerlo puede romper el funcionamiento de la ROM. Si necesitas revertirla, restaura una copia de seguridad anterior a su instalación.
|}

Estas funcionalidades son opcionales: puedes dejar deshabilitada la que entra en conflicto y seguir utilizando los demás sistemas de Dynamic Xtreme, respetando sus dependencias. Deshabilitar una opción no deshace los cambios de otro parche ni elimina la restricción de desinstalación de <code>KevinLMVRAMOptimization</code>.

=== Espacios de RAM utilizados ===

Las direcciones principales se configuran en <code>ASM/DXDefines.asm</code>, dentro de la carpeta de Dynamic Xtreme. En el repositorio, ese archivo corresponde a <code>DynamicXtremeLibrary/ASM/DXDefines.asm</code>.

El espacio utilizado depende de las funcionalidades habilitadas y de si la ROM utiliza SA-1. Los siguientes rangos incluyen el primer y el último byte y están calculados con '''todas las funcionalidades que reservan RAM habilitadas''', <code>!VRAMTransferSize = 64</code> y <code>!CGRAMTransferSize = 64</code>:

{| class="wikitable"
! Configuración !! Bloque <code>!Variables</code> !! Tamaño !! Bloque <code>!Variables2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2000–$7E2500</code> || <code>$0501</code>: 1281 bytes || <code>$7E2800–$7E3608</code> || <code>$0E09</code>: 3593 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB440–$7FB940</code> || <code>$0501</code>: 1281 bytes || <code>$7F9C80–$7FAA88</code> || <code>$0E09</code>: 3593 bytes
|-
| SA-1 || <code>$40C000–$40C47E</code> || <code>$047F</code>: 1151 bytes || <code>$418AFF–$419907</code> || <code>$0E09</code>: 3593 bytes
|}

Los dos bloques internos suman '''4874 bytes en LoROM''' y '''4744 bytes en SA-1'''. La diferencia se debe a los 130 bytes del sistema de dibujo que solo se reservan en LoROM. No se ocupa automáticamente el espacio que queda entre los bloques.

Al deshabilitar una funcionalidad se eliminan sus reservas condicionales y cambian las direcciones posteriores. Aumentar <code>!VRAMTransferSize</code> o <code>!CGRAMTransferSize</code> también aumenta el tamaño de sus tablas.

==== Tablas utilizadas por los sprites ====

<code>DX_FreeRams</code> y <code>DX_FreeRams2</code> '''no son espacios disponibles para escribir variables propias''': a partir de esas posiciones se ubican las tablas de sprites de <code>DynamicXSpritesTables.asm</code> y <code>MoreSpriteMiscs.asm</code>. También debes reservarlas si utilizas esos recursos.

Con la misma configuración de la tabla anterior, sus rangos son:

{| class="wikitable"
! Configuración !! Tablas desde <code>DX_FreeRams</code> !! Tamaño !! Tablas desde <code>DX_FreeRams2</code> !! Tamaño
|-
| LoROM con <code>Free7E2000</code> || <code>$7E2501–$7E26EC</code> || 492 bytes || <code>$7E3609–$7E3824</code> || 540 bytes
|-
| LoROM sin <code>Free7E2000</code> || <code>$7FB941–$7FBB2C</code> || 492 bytes || <code>$7FAC82–$7FAE9D</code> || 540 bytes
|-
| SA-1 || <code>$40C47F–$40C6D8</code> || 602 bytes || <code>$419908–$419BCD</code> || 710 bytes
|}

Incluyendo estas tablas, el espacio descrito suma '''5906 bytes en LoROM''' y '''6056 bytes en SA-1'''. Las tablas se calculan para 12 sprites normales en LoROM y 22 en SA-1, además de los slots de cluster, extended y smoke correspondientes.

Normalmente, <code>DX_FreeRams2</code> comienza justo después del segundo bloque interno. En LoROM sin <code>Free7E2000</code> se coloca por separado mediante <code>!Variables3 = $7FAC82</code>; por eso sus tablas no empiezan inmediatamente después de <code>!Variables2</code>.

Dynamic Xtreme también utiliza los espejos existentes del color fijo y de la paleta: <code>$7E0701</code> (2 bytes) y <code>$7E0703</code> (512 bytes) en LoROM. En SA-1 sus direcciones declaradas son <code>$406701</code> y <code>$006703</code>. No son reservas adicionales dentro de los bloques anteriores ni direcciones libres para tus códigos.

==== Reubicar la RAM si hay un conflicto ====

Si otro recurso utiliza alguno de estos espacios, puedes modificar '''<code>ASM/DXDefines.asm</code>''' para hacer que Dynamic Xtreme utilice otras zonas disponibles de tu romhack.

* Cambia <code>!Variables</code> y <code>!Variables2</code> en la configuración correspondiente a tu ROM: LoROM con <code>Free7E2000</code>, LoROM sin esa opción o SA-1.
* En LoROM sin <code>Free7E2000</code>, revisa también <code>!Variables3</code>, que determina dónde empiezan las tablas de <code>DX_FreeRams2</code>.
* Reserva espacio suficiente para el bloque completo y las tablas de sprites que le siguen. No basta con que la primera dirección esté libre.
* Respeta el mapa de memoria y los bancos que necesitan las rutinas. No cualquier dirección libre sirve para cualquier acceso.
* Después de cambiar las direcciones, reinstala Dynamic Xtreme y vuelve a insertar PIXI, UberASM y los demás recursos que utilicen sus defines.

Con <code>Free7E2000</code>, Dynamic Xtreme aprovecha el área de RAM que recupera al reubicar los gráficos originales; no la compartas con otros recursos sin comprobar qué parte utiliza. Sin esa opción, las direcciones alternativas pueden coincidir con las de otros recursos habituales. SA-1 utiliza sus propias direcciones y desactiva <code>Free7E2000</code>.

Modifica el archivo de la carpeta '''ASM''', no las copias generadas en <code>ExtraDefines</code> o <code>Patch/ExtraDefines</code>: esas copias se regeneran durante la instalación.

== Recursos hechos con Dynamic Xtreme ==

La mayoría de los recursos desarrollados para Dynamic Xtreme no suelen publicarse en sitios tradicionales como SMW Central debido a que muchos de ellos dependen directamente del framework y sus sistemas avanzados.

En su lugar, los recursos, ejemplos, sistemas y proyectos relacionados con Dynamic Xtreme se encuentran recopilados principalmente en:

https://snestorage.dev

Allí es posible encontrar sprites, sistemas de jugador, efectos gráficos, ejemplos técnicos y otros recursos diseñados específicamente para trabajar con Dynamic Xtreme.

== Conclusión ==

Dynamic Xtreme es un proyecto orientado a modernizar y simplificar el uso de sistemas dinámicos en Super Mario World, ofreciendo herramientas más flexibles, potentes y fáciles de utilizar sin perder compatibilidad ni control avanzado.

El proyecto continúa evolucionando constantemente con nuevas optimizaciones, formatos y herramientas orientadas tanto a usuarios avanzados como a personas que recién comienzan a trabajar con gráficos dinámicos en SNES.

La intención principal de Dynamic Xtreme es permitir la creación de recursos y sistemas cada vez más complejos, manteniendo al mismo tiempo un workflow más limpio, mantenible y accesible para la comunidad.

es/Dynamic Xtreme

2026-10-24T23:12:40Z

Anonimzwx: