Documentation du projet

Source HTML: readme_content.html

Système Économique — Hytale

Présentation

Ce projet définit le système économique du serveur Hytale. Il repose sur un réseau de marchands (NPCs) qui achètent et vendent des ressources aux joueurs via un système d'échanges configurables.

Chaque marchand est spécialisé dans un domaine (chasse, artisanat, magie, etc.) et propose des transactions en monnaie ou en objets.

Plugin utilisé : NPC Trading

Les marchands sont gérés grâce au plugin NPC Trading.

📦 Documentation officielle : https://www.curseforge.com/hytale/mods/npc-trading

Les fichiers de configuration des NPCs se trouvent dans le dossier npcs/.

Chaque fichier JSON peut contenir un ou plusieurs marchands, identifiés par leur UUID.

Structure d'un fichier NPC


{
  "<uuid>": {
    "uuid": "<uuid>",
    "name": "Nom du marchand",
    "trades": [ ... ],
    "citizenIds": [ "<uuid-du-citoyen-lié>" ],
    "rotateItems": false,
    "rotationIntervalMinutes": 5,
    "displayedItemCount": 5,
    "lastRotationTime": 0,
    "currentRotationOffset": 0
  }
}

Propriétés principales

Propriété	Type	Description
`uuid`	`string`	Identifiant unique du marchand
`name`	`string`	Nom affiché du marchand
`trades`	`array`	Liste des échanges proposés
`citizenIds`	`array`	UUIDs des citoyens (instances en jeu) associés à ce marchand
`rotateItems`	`boolean`	Si `true`, les échanges affichés tournent selon un intervalle
`rotationIntervalMinutes`	`number`	Intervalle de rotation des échanges (en minutes)
`displayedItemCount`	`number`	Nombre d'échanges visibles simultanément dans l'interface
`lastRotationTime`	`number`	Timestamp de la dernière rotation (géré automatiquement)
`currentRotationOffset`	`number`	Décalage actuel dans la liste d'échanges (géré automatiquement)

Structure d'un échange (`trade`)

Chaque échange définit ce que le marchand demande (inputs) et ce qu'il donne (outputs).


{
  "inputs": [
    {
      "type": "CURRENCY",
      "currency": "Euro",
      "amount": 35.0
    }
  ],
  "outputs": [
    {
      "type": "ITEM",
      "itemId": "Ingredient_Leather_Light",
      "quantity": 1.0
    }
  ],
  "maxStock": -1.0,
  "currentStock": 0.0,
  "restockAmount": 0.0,
  "restockIntervalMs": 0.0,
  "lastRestockTime": 0.0
}

Types d'entrée/sortie

`type`	Champs supplémentaires	Description
`CURRENCY`	`currency` (string), `amount` (float)	Paiement ou remboursement en monnaie
`ITEM`	`itemId` (string), `quantity` (float)	Échange d'un objet du jeu

Propriétés de stock

Propriété	Description
`maxStock`	Stock maximum. `-1` = illimité
`currentStock`	Stock actuel disponible
`restockAmount`	Quantité réapprovisionnée à chaque intervalle
`restockIntervalMs`	Intervalle de réapprovisionnement en millisecondes (`0` = pas de restock)
`lastRestockTime`	Timestamp du dernier réapprovisionnement (géré automatiquement)

Exemple : Marchand Chasseur

Le fichier npcs/sample.json définit un marchand nommé "Marchand Chasseur".

Il achète et vend trois types de cuir :

Objet	Prix de vente (joueur → achat)	Prix de rachat (joueur → vente)
`Ingredient_Leather_Light`	35 €	18 €
`Ingredient_Leather_Medium`	70 €	35 €
`Ingredient_Leather_Heavy`	120 €	60 €

Le stock est illimité (maxStock: -1) et aucun réapprovisionnement automatique n'est configuré.

Référence des items

Le fichier ITEMS.md répertorie l'ensemble des 2942 items du jeu Hytale, extraits automatiquement depuis la base de données officielle (FULL_DB).

Pour chaque item, les informations suivantes sont disponibles :

Colonne	Description
Catégorie	Catégorie racine de l'item (`root_category`)
Sous-catégorie	Sous-catégorie de l'item (`sub_category`)
ID	Identifiant technique de l'item (`id`)
Nom d'affichage	Nom lisible de l'item (`display_name`)
Famille	Famille de l'item (`Tags.Family`)
Type	Type de l'item (`Tags.Type`)
Rareté	Rareté de l'item (`Quality`)
Item Level	Niveau requis de l'item (`ItemLevel`)

Ce fichier est généré par le script extract_items.py et peut être regénéré à tout moment si la base de données est mise à jour.

Organisation du projet


economie/
├── README.md            ← Ce fichier
├── ITEMS.md             ← Référence de tous les items Hytale (2942 entrées)
├── extract_items.py     ← Script de génération de ITEMS.md
└── npcs/
    └── sample.json      ← Exemple de marchand (Marchand Chasseur)

Au fil du développement, de nouveaux fichiers JSON seront ajoutés dans npcs/ pour chaque type de marchand (forgeron, alchimiste, fermier, etc.).