scaling

Cookbook-Battle-And-Mechanics.md

@@ -84,3 +84,26 @@ mod.content.type_chart:register("FAIRY>DRAGON", { multiplier = 20 })
 Checkpoint: FAIRY hits Dragons super-effectively. `multiplier` is base
 10; bare ids are types (mind `PSYCHIC_TYPE`), `"A>B"` ids are matchup
 rows — one registry holds both.
+
+## R36 - Scale a battle sprite
+
+<!-- snippet: run -->
+```lua
+-- MEW's back pic renders 1.5x; its front pic is untouched
+mod.content.pokemon:patch("MEW", { battleScaleBack = 1.5 })
+
+-- or target one image by path (beats the species scale for that pic)
+mod.content.battle_sprite_scales:register("abra_back", {
+  path = "assets/generated/battle/back/abrab.png",
+  scale = 1.5,
+})
+```
+
+Checkpoint: the rescaled pic draws bigger with its feet still flush on
+the ground line. Defaults are 1x front / 2x back, exactly the Game Boy
+layout; `battleScaleFront` scales the enemy pic, `battleScaleBack` the
+player pic, both `0.25 .. 4.0`. The image-level registry is the only way
+to reach non-species pics such as the player's trainer back sprite.
+Anchoring and the send-out grow are handled for you
+(`src/battle/BattleState.lua` `resolveBattleScale`, `frontPlacement`,
+`backPlacement`).

Cookbook.md

@@ -42,6 +42,7 @@ thing. Each recipe links the concept page that explains its mechanism.
 | R33 | Persist mod state | `mod.save:get/set` | [UI and Infrastructure](Cookbook-UI-And-Infrastructure) |
 | R34 | Define a mod option | `mod.options:define` | [UI and Infrastructure](Cookbook-UI-And-Infrastructure) |
 | R35 | Export an inter-mod API | `mod.exports` + `mod.find` | [UI and Infrastructure](Cookbook-UI-And-Infrastructure) |
+| R36 | Scale a battle sprite | `battle_sprite_scales:register` / `pokemon:patch` | [Battle and Mechanics](Cookbook-Battle-And-Mechanics) |
 
 No recipe reaches the total-conversion tier — that is a guided rung
 ([Tutorial 12](Tutorial-12-Mini-Total-Conversion)), not a copy-paste

Guide-Art-Pipeline.md

@@ -12,7 +12,11 @@ contract picks up map/battle palettes for free. Battle pics treat shade 0
 (white) as transparency — the matte pass strips it.
 
 - Battle sprites: square, tile-aligned; the species record's `frontSize`
-  (1–7, in 8px tiles) drives battle layout.
+  (1–7, in 8px tiles) drives battle layout. Draw scale is moddable per
+  species (`battleScaleFront`/`battleScaleBack`, defaults 1x front and
+  2x back) or per image path (`battle_sprite_scales` registry); the pic
+  stays grounded at any scale
+  ([Reference: Registries](Reference-Registries#battle_sprite_scales)).
 - Overworld sprites (`sprites` registry): 16×16 frames stacked into one
   sheet; a full walking character is a 16×96 six-frame sheet with
   `walker = true`. See
@@ -84,7 +88,13 @@ on a real run.
 ## Palettes, icons, fonts
 
 - `palettes` — four colors per record, raw `{ {r,g,b}, ... }` quadruple
-  or `{ colors = { {r=,g=,b=}, ... } }`; exactly 4, validated.
+  or `{ colors = { {r=,g=,b=}, ... } }`; exactly 4, validated. To give a
+  **species** those colors, set `palette = "<that id>"` on its `pokemon`
+  record: the battle renderer honors a record's own `palette` field before
+  the vanilla species→palette map (`src/render/PaletteFX.lua`), so a new or
+  dex-renumbered species keeps the palette it registers. A species with no
+  `palette` field falls back to the vanilla mapping (or the `MEWMON`
+  default) unchanged.
 - `icons` — party icons keyed by **species id**, drawn by the party menu
   (`src/ui/PartyMenu.lua`) and taking precedence over the vanilla
   dex-indexed default, so a modded or dex-renumbered species keeps the icon

Reference-Registries.md

@@ -71,6 +71,32 @@ mod.content.balls:override("GREAT_BALL", { randMax = 180, hpFactor = 12 })
 mod.content.battle_anims:register("SHADOW_BALL", { seq = { ... } })
 ```
 
+## battle_sprite_scales
+
+- semantics: `record`
+- target: `Data.battle_sprite_scales`
+
+| field | type | required |
+|---|---|---|
+| `path` | file path | yes |
+| `scale` | number 0.25..4 | yes |
+
+```lua
+mod.content.battle_sprite_scales:register("abra_back", {
+  path = "assets/generated/battle/back/abrab.png",
+  scale = 1.5,
+})
+```
+
+Scales one battle pic by its asset path, overriding the species-level
+`battleScaleFront`/`battleScaleBack` (see [pokemon](#pokemon)) for that
+image. The only way to scale a pic that is not species-keyed, like the
+player's trainer back sprite. Resolution order at draw time:
+image-level, then species-level, then the defaults (1x front, 2x back).
+The pic stays grounded at any scale: player feet stay flush on the
+text-box top, the enemy pic stays bottom-pinned in its slot, and the
+scale composes with the send-out grow animation.
+
 ## commands
 
 - semantics: `record`
@@ -381,6 +407,8 @@ mod.content.palettes:override("MEWMON", { {255,255,255}, ... })
 |---|---|---|
 | `baseExp` | integer 0..255 | yes |
 | `baseStats` | {attack, defense, hp, special, speed} | yes |
+| `battleScaleBack` | number 0.25..4 | no |
+| `battleScaleFront` | number 0.25..4 | no |
 | `catchRate` | integer 0..255 | yes |
 | `cry` | cries id | no |
 | `dex` | integer >= 1 | yes |