unite-lib 1.1.0 → 1.3.0

package/README.md

@@ -47,18 +47,24 @@ const cdnImg = getImageUrl(pikachu, "main", {
 ### i18n (localized names)
 
 ```js
-import { getPokemonName } from "unite-lib";
+import { getPokemonName, getMapName, getMapDescription } from "unite-lib";
 // or
-import { getPokemonName } from "unite-lib/i18n";
+import { getPokemonName, getMapName, getMapDescription } from "unite-lib/i18n";
 
+// Pokémon names
 getPokemonName("venusaur", "en");    // "Venusaur"
 getPokemonName("venusaur", "pt-BR"); // "Venusaur"
 getPokemonName("venusaur", "ja-JP"); // "フシギバナ"
 getPokemonName("venusaur", "fr");    // "Florizarre"
 getPokemonName("venusaur", "es");    // "Venusaur"
+
+// Map names and descriptions (optional — use when you need localized UI)
+getMapName("map-groudon", "en");       // "Theia Sky Ruins"
+getMapName("map-groudon", "pt-BR");   // "Ruínas Celestes de Theia"
+getMapDescription("map-groudon", "es"); // "Mapa 5v5 con Groudon."
 ```
 
-Supported locales: `en`, `pt-BR`, `ja-JP`, `fr`, `es`.
+Supported locales: `en`, `pt-BR`, `ja-JP`, `fr`, `es`. Each map in `maps` has a default `name` and `description` (English); use `getMapName(mapId, locale)` and `getMapDescription(mapId, locale)` when you want to show them in another language.
 
 ## Content
 
@@ -84,10 +90,14 @@ Move images (slot 1 and 2, variants 1 and 2) per Pokémon.
 
 ### Maps
 
-Game map images (Remoat Stadium, Theia Sky Ruins, Mer Stadium, etc.).
+Game map images (Theia Sky Ruins variants: Groudon, Kyogre, Rayquaza). Each map has multiple resolutions (1x, 2x, 4x); use `getMapImageUrl(map, resolution?, options?)` to pick one. Names and descriptions are available in all supported locales via `getMapName(mapId, locale)` and `getMapDescription(mapId, locale)` (see [i18n](#i18n-localized-names)).
 
 ![Map](https://raw.githubusercontent.com/cesaroeduardo/unite-lib/main/maps/groudon.png)
 
+### Neutrals and spawns
+
+The library includes a **neutrals** catalog (wild Pokémon and items that spawn on maps) with images in `neutrals/`, and a unified **spawns** list in `src/spawns.ts` (same pattern as `pokemons.ts`) linking each spawn to a map and a neutral. Use `getSpawnsByMap(mapId)` to get all spawns for a map (e.g. `"map-groudon"`, `"map-kyogre"`, `"map-rayquaza"`), `getNeutralById(id)` to resolve the neutral (e.g. for its image), and `getNeutralImageUrl(neutral, options?)` for the image URL.
+
 ---
 
 ## Local development (testing without publishing to npm)
@@ -173,17 +183,27 @@ Asset URLs via jsDelivr (substitua `@latest` por uma versão se quiser):
 |--------|-------------|
 | `pokemons` | Full roster (name, dex, images, battleType, stats, tags, difficulty) |
 | `moves` | Move list (pokemonId, slotId, name, image) |
-| `maps` | Map list (id, name, image, description) |
+| `maps` | Map list (id, name, image, images by resolution, description) |
+| `neutrals` | Neutral catalog (id, image; wild Pokémon/items for spawns) |
+| `spawns` | All map spawns (mapId, neutralId, left, top, spawnTime, respawnTime, etc.) |
 | `BattleType` | `attacker`, `defender`, `allrounder`, `speedster`, `supporter` |
 | `Tag` | Role + style: `attacker`, `defender`, `melee`, `ranged`, … |
 | `getImageUrl(pokemon, key, options?)` | Image path or full URL with `baseUrl` |
+| `getMapImageUrl(map, resolution?, options?)` | Map image URL (resolution: `"1"`, `"2"`, `"4"`) |
+| `getNeutralImageUrl(neutral, options?)` | Neutral image path or full URL |
+| `getSpawnsByMap(mapId)` | Spawns for a map (e.g. `"map-groudon"`) |
+| `getNeutralById(id)` | Find neutral by id |
 | `getPokemonByName(name)` | Find by display name |
 | `getPokemonByDex(dex)` | Find by Pokédex number |
 | `getPokemonBySlug(slug)` | Find by slug (e.g. `venusaur`) |
 | `getPokemonsByBattleType(type)` | Filter by BattleType |
 | `getPokemonsByTag(tag)` | Filter by Tag |
 | `getActivePokemons()` | Only active roster entries |
-| `getPokemonName(slug, locale)` | Localized name (from main package or `unite-lib/i18n`) |
+| `getPokemonName(slug, locale)` | Localized Pokémon name (from main package or `unite-lib/i18n`) |
+| `getMapName(mapId, locale)` | Localized map name |
+| `getMapDescription(mapId, locale)` | Localized map description |
+
+Types: `Neutral`, `MapSpawn` (see also `Map`, `MapResolution`, `Pokemon`, `Move`, etc.).
 
 ## Project structure
 
@@ -191,6 +211,7 @@ Asset URLs via jsDelivr (substitua `@latest` por uma versão se quiser):
 - **`pokemons/`** — Roster and stat images
 - **`moves/`** — Move images
 - **`maps/`** — Map images
+- **`neutrals/`** — Wild Pokémon and item images used in map spawns
 - **`.cursor/skills/`** — [Cursor Agent Skills](https://docs.cursor.com/context/agent-skills) for use with AI agents in this repo (e.g. syncing roster from images in `pokemons/` and `moves/`).
 - **`mcp/`** — [MCP server](mcp/README.md) (Model Context Protocol) para consumir a library em agentes de IA: tools para listar e buscar pokémons, moves, mapas, URLs de imagens e nomes localizados (Cursor, Claude Desktop, etc.).