roleplay-data 0.1.0

package/CREDITS.md

@@ -0,0 +1,34 @@
+# CREDITS
+
+`roleplay-data` est une **base de données RP open source** : les données, les visuels et les
+traductions sont le fruit de contributions multiples.
+
+> 💛 Merci d'apprécier le travail : quand vous utilisez ce projet (ou ses données) dans le
+> vôtre, un petit crédit fait toujours plaisir — un lien, une ligne dans votre README,
+> une page « À propos ». Ce n'est pas une obligation, juste une attention.
+
+## Auteurs / projets fondateurs
+
+| Qui | Contribution |
+|---|---|
+| **Amity Studio — Stananas** | Catalogue initial des items, système de thèmes, structure du projet, package npm |
+| **Amity RolePlay V2 (bot + sites)** | Les données proviennent initialement de l'écosystème Amity RolePlay |
+
+## Sources des visuels
+
+Certains visuels des packs de thèmes s'inspirent de jeux existants. Chaque thème déclare
+sa licence / son attribution dans `themes/themes.json` :
+
+| Thème | Origine des visuels |
+|---|---|
+| `gta-artwork` | Inspirés de GTA V © Rockstar Games — usage non commercial |
+| `dayz` | Générés par la communauté Amity Studio (MIT) |
+
+Si vous ajoutez un thème ou des images, créez vous aussi une entrée dans le registre
+`themes/themes.json` (licence + attribution).
+
+## Contribuer au crédit
+
+Quand vous contribuez (PR acceptée), ajoutez votre nom / pseudo ici en une ligne :
+
+- ...

package/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Amity Studio — Stananas & contributeurs
+
+Permission est hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+--------------------------------------------------------------------------------
+
+Remarque sur les crédits (non contraignante) :
+
+Les contributeurs sont chaleureusement invités à mentionner le projet
+`roleplay-data` et leur propre contribution (nom ou pseudo) dans leurs propres
+projets, via un lien, un CREDITS, une page « À propos » ou un simple merci.
+Cette mention est une marque d'appréciation, pas une obligation contractuelle.

package/README.md

@@ -0,0 +1,163 @@
+# roleplay-data
+
+**Base de données RP open source** : items, véhicules, thèmes (packs d'images +
+renommages) et i18n. Une source de vérité unique, consommable partout :
+
+- 📦 **package npm** pour vos services (bot Discord, sites, API)
+- 🗄️ **seed SQL / MongoDB** prêt à injecter (catalogues, thèmes)
+- 📦 **archive ZIP** des assets pour une version donnée (FiveM, ESX, serveurs custom)
+
+> 🇫🇷 🇬🇧 Conventions : la langue source des données est **fr + en** (obligatoires),
+> toute autre locale est une contribution bonus.
+
+---
+
+## Structure
+
+```
+catalog/                  ✨ données canoniques
+├── items.json             166 items (nom, description i18n, poids, stats, tags…)
+├── vehicles.json          10 modèles de véhicules (marque/modèle i18n, catégorie, specs, cargo)
+└── schemas/               JSON Schema : la validation CI les applique aux PR
+themes/                   🎨 systèmes de thèmes (packs d'images + renommages + exclusifs)
+├── themes.json            le registre : un thème est déclaré une fois, partout consommé
+├── gta-artwork.json       renommages « monde GTA V » (ex: arme Beretta → « Pistol »)
+└── dayz.json              renommages + items exclusifs DayZ
+assets/                   🖼️ images (brutes en git — LFS later)
+├── items/gta-artwork/     pack d'images par défaut (référence)
+├── items/dayz/            pack d'images du thème DayZ
+└── no_image.png           fallback universel
+src/                      📦 l'API du package (zéro dépendance)
+├── index.js               chargement + cache + API publique
+├── resolve.js             résolution thème (image fallback gta-artwork → no_image, overrides, exclusifs)
+├── localize.js            i18n (fallback en)
+└── index.d.ts             types TypeScript
+scripts/                  🔧 outils de maintenance
+├── validate.mjs           validation (schéma, unicité des ids, cohérence thèmes, images)
+└── build-release.mjs      génère dist/ : package npm + seed SQL + seed MongoDB + ZIP
+```
+
+---
+
+## Exemples d'items
+
+```json
+{
+  "id": "weapon_beretta",
+  "name": { "fr": "Beretta", "en": "Beretta" },
+  "description": { "fr": "Un pistolet semi-automatique fiable.", "en": "A reliable semi-automatic pistol." },
+  "image": "weapon_beretta.png",
+  "emoji": "🔫",
+  "weight": 950,
+  "food": 0, "thirst": 0, "drug": null,
+  "stackable": false, "usable": false,
+  "tags": ["weapon"],
+  "metadata": { "irl": { "model": "Beretta 92FS", "fabricant": "Beretta", "caliber": "9×19 mm Parabellum" } },
+  "customProperties": {}
+}
+```
+
+- `metadata` : identité réelle de l'objet — sert de base au **renommage par thème**
+  (voir `themes/gta-artwork.json` : la même arme porte son nom GTA V dans ce thème).
+- `customProperties` : **point d'extension libre** pour vos besoins propres,
+  sans jamais modifier le schéma.
+
+## Exemple de thème
+
+```json
+// themes/gta-artwork.json — renommage monde GTA V
+{ "overrides": [ { "id": "weapon_beretta", "name": { "fr": "Pistol", "en": "Pistol" } } ], "exclusiveItems": [] }
+```
+
+Règles des thèmes :
+- les **overrides** ne touchent que les champs fournis (fusion sur l'item du catalogue) ;
+- les **exclusiveItems** n'existent que dans le thème (ex: `aks74u` en DayZ) ;
+- les **virtualIds** autorisent des overrides sur des ids créés par le code (ex: `money_clean`) ;
+- une image absente du pack du thème **retombe sur le pack `gta-artwork`**, puis sur `no_image.png`.
+
+> ⚖️ **Neutralité des données** : le registre ne contient **aucune notion de
+> monétisation** (pas de champ `premium`). Le fait qu'un thème soit gratuit,
+> payant, réservé, exclusif, etc. est une décision **du projet consommateur** —
+> pas une propriété de la donnée. Si vous monétisez certains thèmes, gérez ce
+> mapping dans la config de votre projet, pas ici.
+
+---
+
+## Consumption
+
+### npm
+
+```bash
+npm install roleplay-data
+```
+
+```js
+import { getItems, getItem, getThemedItemName, getItemImage } from 'roleplay-data';
+
+getItems();                                  // 166 items canoniques
+getThemedItemName('burger', 'dayz', 'fr');   // "Conserve DayZ"
+getItemImage('aks74u', 'dayz');              // thème → gta-artwork → no_image
+```
+
+### SQL (PostgreSQL)
+
+```bash
+node scripts/build-release.mjs && psql -U postgres -d ma_base -f dist/sql/roleplay-data.sql
+```
+
+Tables : `rp_items`, `rp_vehicles`, `rp_themes`, `rp_theme_entries`.
+
+### MongoDB
+
+```bash
+mongoimport --db roleplay-data --collection items --file dist/mongodb/seed.items.json
+mongoimport --db roleplay-data --collection vehicles --file dist/mongodb/seed.vehicles.json
+mongoimport --db roleplay-data --collection themes --file dist/mongodb/seed.themes.json
+```
+
+### Archives
+
+Chaque release GitHub embarque `roleplay-data-vX.Y.Z.zip` (catalog + themes + assets + docs).
+
+---
+
+## Contribuer
+
+1. `npm run validate` doit passer en local (⚠️ 8 warnings connus = images manquantes, voir ci-dessous).
+2. Une PR = un sujet : ajouter un item / un véhicule / un thème / une traduction, ou corriger des données.
+3. Ne **jamais** casser les ids existants (rétro-compatibilité).
+4. La CI `validate` vérifie schémas, unicité, cohérence des thèmes et existence des images.
+
+### Images manquantes connues (bonnes premières issues)
+
+Les items suivants pointent vers des images qui n'existaient déjà pas dans le jeu source —
+parfaits pour un premier PR « ajouter une image » :
+
+`poisson_propre`, `pioche`, `lanterne_mini`, `minerai`, `minerai_rare`, `lingot`, `hache`, `bois`
+
+Ajoutez le fichier `assets/items/gta-artwork/<id>.png` et le warning disparaît.
+
+### Assets & Git LFS
+
+Actuellement les images sont **committées telles quelles** (fichiers de 3-4 Ko
+chacun, ~30 Mo au total — aucun souci pour git/GitHub). Le **Git LFS** sera
+adopté quand un pack deviendra lourd — la procédure de migration est documentée
+dans `assets/README.md`.
+
+---
+
+## Feuille de route
+
+- [x] v0.1 — items + véhicules + thèmes + i18n + validation + builds multi-produits
+- [ ] habitations (`catalog/properties.json`), drogues, jobs
+- [ ] images de véhicules (`assets/vehicles/`)
+- [ ] API items/thèmes (hostée)
+- [ ] migration des services Amity vers `roleplay-data` (fin des copies locales)
+- [ ] publication npm + releases GitHub automatisées
+
+---
+
+## Licence
+
+MIT — libre, code et données. Une mention (crédit) est appréciée, jamais obligatoire.
+Voir `LICENSE` et `CREDITS.md`.

package/assets/README.md

@@ -0,0 +1,38 @@
+# Assets — roleplay-data
+
+Ce dossier contient les **images** des packs de thèmes. Il est versionné avec
+**Git LFS** — pensez à `git lfs install` après clonage.
+
+```
+assets/
+└── items/
+    ├── gta-artwork/  pack d'images de référence (par défaut)
+    ├── dayz/         pack d'images du thème DayZ
+    └── no_image.png  fallback universel (affiché quand une image manque)
+```
+
+## Règles
+
+- Le fichier référencé par un item dans `catalog/items.json` doit exister dans `items/gta-artwork/`.
+- Le fichier référencé par un thème peut exister dans `items/<thème>/` (et retombe sur `items/gta-artwork/` sinon).
+- Conventions de nommage fichiers : `snake_case.png`, sans espace ni accent.
+- Pas de sous-dossier dans `items/`.
+- Toute image doit être au format PNG (fond transparent recommandé pour les items).
+
+## Vérification
+
+`npm run validate` signale en warning toute image référencée et introuvable
+(voir README, section « Images manquantes connues »).
+
+## Git LFS (optionnel, plus tard)
+
+Pour l'instant les assets sont **committés tels quels** : les fichiers font
+3-4 Ko chacun (~30 Mo au total), ce qui est très bien géré par git/GitHub.
+
+On basculera en **Git LFS** quand un pack grossira (visuels lourds, vidéos,
+vignettes HD). La migration se fera alors avec :
+
+```bash
+git lfs install
+git lfs migrate import --yes --include="assets/**/*.png" --include-ref=main --include-ref=origin/main
+```