====== Ressources (objets quantifiables et multiples) ======

Une **ressource** est un type d’objet que l’on **accumule en quantité variable** : argent, bois, essence, fruits, points de vie matérialisés… Elle hérite d’[[reference:definitions:objets|objet]] : on la prend, la pose, la donne, la consomme comme un objet ordinaire, mais en **quantités** plutôt qu’à l’unité.

Une ressource est par nature un objet **multiple** : elle existe en plusieurs unités à la fois (état ''multiple'') et n’est ''unique'' que lorsqu’il n’en reste **qu’une seule** (quantité 1).

Chaque ressource possède une **unité** de comptage (« pièce », « litre », « unité »…), explicite ou par défaut.

===== Définir une ressource =====

On déclare une ressource comme une classe d’objet, puis on en place une quantité avec ''Il y a N … '' :

<file donjon wiki_ressources_definir>
-- Trois façons de déclarer une ressource, puis on la place en quantité.
L'atelier est un lieu.

-- ressource « massive » : sans unité déclarée, l'unité par défaut est « unité »
Le bois est une ressource.
Il y a 30 unités de bois ici.

-- ressource avec une unité explicite
L'argent est une ressource exprimée en pièces.
Il y a 5 pièces d'argent ici.

-- ressource déclarée au pluriel : comptée par son propre nom
Les fruits sont une ressource.
Il y a 4 fruits dans l'atelier.
</file>

[[djnc>wiki_ressources_definir|tester cet exemple]] — tapez ''regarder'' : le moteur affiche « 30 unités de bois », « 5 pièces d’argent » et « 4 fruits ».

Tous les déterminants conviennent — l’article **défini** (''le'' / ''la'' / ''les'' / ''l’'') comme **indéfini** (''un'' / ''une'' / ''des'') — et le genre est déduit de l’article :

<code donjon>
Une pomme est une ressource.
Des graines sont des ressources.
</code>

Dans tous les cas, déclarer une ressource crée une **classe** à son nom (''pomme'', ''bois''…) héritant de ''ressource'' : les règles et actions peuvent donc la cibler (''règle après manger une pomme'', ''action cueillir une pomme'').

<note>La forme **avec position attachée** (''… est une ressource ici'' ou ''… sur la table'') n’accepte que ''le'' / ''la'' / ''les'' / ''l’''. Avec un article indéfini, déclarez la ressource puis placez-la séparément : ''Une pomme est une ressource.'' puis ''Il y a 3 pommes sur la table.''</note>

==== Attributs par défaut ====

Les adjectifs/attributs ajoutés à la définition deviennent les **états par défaut de la classe** de la ressource : **chaque** pile (ou objet) de cette ressource en hérite, y compris les piles placées séparément avec ''Il y a …''.

<code donjon>
Les pommes sont des ressources mangeables, rouges et vertes.
Il y a 3 pommes dans le panier.   -- chaque pomme hérite des états mangeable, rouge et vert
</code>

On liste les états séparés par des virgules et ''et'', comme pour une [[reference:definitions:classes|classe]] ordinaire. C’est ce qui rend les ''ressource mangeable'' des exemples ci-dessous réellement mangeables.

<WRAP info>À ne pas confondre avec l’état ''multiple'' : celui-ci n’est pas un état de classe mais se déduit de la **quantité** de chaque pile (≠ 1 → ''multiple'', = 1 → ''unique'').</WRAP>

==== Unité de comptage ====

Selon la déclaration, **sans** unité explicite :

  * ressource déclarée **au pluriel** (« Les fruits ») → comptée par son nom : « 5 fruits » ;
  * ressource déclarée **au singulier** / nom massif (« Le bois ») → unité par défaut « unité(s) » : « 30 unités de bois ».

Trois façons de déclarer une unité **explicite** (le moteur en dérive automatiquement le singulier et le pluriel) :

<code donjon>
L'argent est une ressource exprimée en pièces.   -- unité donnée au pluriel
L'eau est une ressource avec l'unité litre.        -- unité donnée au singulier
Le sable est une ressource.
Son unité est le grain.                            -- séparément, après la définition
</code>

=== Genre de l'unité ===

L'unité a son **propre genre** grammatical (« pièce » féminin), qui peut différer de celui de la ressource (« or » masculin). Il commande les accords des messages (« 3 pièces d'or **ont été ajoutées** »). Par défaut **masculin** ; déduit de l'article (''la'' → féminin, ''le'' → masculin) s'il est présent ; ou forcé par le marqueur ''(f)'' / ''(m)'' :

<code donjon>
L'or est une ressource exprimée en pièces (f).
Le minerai est une ressource. Son unité est la pépite.
L'eau est une ressource avec l'unité litre (m).
</code>

==== Placer des quantités ====

Les nombres s’écrivent en **chiffres**. Les emplacements possibles sont ''ici'', ''dans …'', ''sur …'', ''sous …'' :

<code donjon>
Il y a 30 unités de bois ici.
Il y a 5 pièces d'argent dans le coffre.
Il y a 3 unités d'essence sous la table.
</code>

Une même ressource peut former **plusieurs piles indépendantes** :

<code donjon>
Il y a 5 pièces d'argent dans le coffre.
Il y a 3 pièces d'argent sur la table.   -- deux piles distinctes : 5 et 3
</code>

<WRAP info>Une ressource déclarée mais **jamais placée** vaut **0** : le type existe, mais il n’y en a aucune dans le monde tant qu’on n’en place ou n’en crée pas.</WRAP>

===== Commandes du joueur =====

Les commandes habituelles acceptent une **quantité** et l’**unité**. Le joueur désigne la ressource par son unité (« les pièces ») ou par « unité de ressource » (« les pièces d’argent ») pour lever une ambiguïté.

<file donjon wiki_ressources_commandes>
-- Les commandes habituelles fonctionnent avec des quantités et l'unité.
Le marché est un lieu.
Le marchand est une personne ici.

L'argent est une ressource exprimée en pièces.
Il y a 10 pièces d'argent ici.

Les fruits sont une ressource mangeable.
Il y a 5 fruits dans le marché.
</file>

[[djnc>wiki_ressources_commandes|tester cet exemple]] — après ''regarder'', essayez :

  * ''prendre les pièces'' — prend toute la pile
  * ''donner 3 pièces d’argent au marchand''
  * ''prendre les fruits'' puis ''manger 2 fruits''

''déposer'' est un synonyme de ''poser'' (« déposer 2 fruits sur la table »).

===== Manipuler les ressources dans les règles =====

À l’intérieur des règles, réactions et actions personnalisées, trois instructions agissent sur les ressources :

  * ''créer N <unité> de X dans/sur/sous <cible>'' — fait apparaître N unités à un emplacement (''dans l’inventaire'', un contenant, un support, un lieu) ;
  * ''consommer N <unité> de X'' — retire N unités possédées (elles disparaissent) ;
  * ''déplacer [les | N] <unité> de X depuis <source> vers <destination>'' — transfère une pile d’un emplacement à un autre.

Les emplacements reconnus sont ''l’inventaire'', ''l’intérieur du <contenant>'', ''le dessus du <support>'', ''le dessous du <support>'', ou un lieu/contenant/support nommé.

<file donjon wiki_ressources_instructions>
-- Manipuler une ressource par script dans des règles (ici, des actions personnalisées).
Le sanctuaire est un lieu.
Le coffre est un contenant ouvert ici.

L'or est une ressource exprimée en pépites.
Il y a 8 pépites d'or dans le coffre.

-- créer : fait apparaître de nouvelles unités à un emplacement
action invoquer:
  phase exécution:
    créer 3 pépites d'or dans l'inventaire.
  phase épilogue:
    dire "Trois pépites d'or se matérialisent dans votre main.".
fin action

-- déplacer … depuis … vers … : transfère une pile d'un emplacement à un autre
action piller:
  phase exécution:
    déplacer les pépites d'or depuis l'intérieur du coffre vers l'inventaire.
  phase épilogue:
    dire "Vous raflez l'or du coffre.".
fin action

-- consommer : retire des unités possédées (elles disparaissent)
action dépenser:
  phase exécution:
    consommer 5 pépites d'or.
  phase épilogue:
    dire "Vous dépensez 5 pépites d'or.".
fin action
</file>

[[djnc>wiki_ressources_instructions|tester cet exemple]] — tapez ''invoquer'' (crée 3 pépites), ''piller'' (vide le coffre vers l’inventaire), puis ''dépenser'' (en retire 5).

===== Afficher dans le cartouche =====

Une ressource s’affiche dans le **cartouche** (la barre fixe du lecteur) exactement comme un [[reference:memoire:compteurs|compteur]]. La quantité est calculée **en direct** : prendre, lâcher, consommer ou créer la ressource met le cartouche à jour automatiquement.

<code donjon>
L'argent est affiché en haut à droite.
Le bois est affiché en bas à gauche.
</code>

Positions possibles : ''haut'' ou ''bas'', combiné à ''gauche'' ou ''droite''. Si on omet la latéralité, c’est ''droite'' ; si on omet la verticalité, c’est ''haut''.

==== Périmètre : possédé ou disponible ====

Un mot-clé optionnel, placé **après le nom**, choisit les piles à additionner :

  * **possédé** (par défaut) — uniquement ce que le **joueur transporte** ;
  * **disponible** — **tout sauf** l’inventaire du joueur (piles posées dans les lieux, dans des coffres, portées par des PNJ…).

Les deux périmètres sont complémentaires : leur somme couvre toutes les piles de la ressource, sans recouvrement.

<code donjon>
L'argent possédé est affiché en haut à droite.    -- ce que le joueur porte
Le bois disponible est affiché en haut à gauche.   -- ce qu'il reste à ramasser
</code>

==== Options ====

Comme pour les compteurs, on peut masquer l’intitulé et/ou l’unité :

<code donjon>
L'argent est affiché en haut à droite sans intitulé.
L'argent est affiché en haut à droite sans unité.
L'argent est affiché en haut à droite sans intitulé sans unité.
</code>

L’unité s’accorde automatiquement (singulier à 0 ou 1, pluriel au-delà). Une pile illimitée affiche « ∞ ». L’entrée reste visible même à 0 (elle affiche « 0 », elle ne disparaît pas).

==== Modifier l’affichage en cours de partie ====

Comme pour les compteurs, on peut repositionner, masquer ou (ré)afficher une ressource depuis une règle, une action ou une réaction avec ''changer'' :

<code donjon>
changer l'argent est affiché en bas à gauche.             -- repositionner
changer l'argent est affiché en haut à droite sans intitulé.  -- changer les options
changer l'argent n'est plus affiché.                      -- retirer du cartouche
</code>

  * ''changer … est affiché …'' sur une ressource **jamais affichée** auparavant **crée** l’entrée (périmètre ''possédé'').
  * À chaque réaffichage, les options « sans … » sont **réinitialisées** : il faut les redéclarer pour les conserver.
  * Le **périmètre** (''possédé'' / ''disponible'') se choisit à la définition ; ''changer'' ne le modifie pas.

<file donjon wiki_ressources_cartouche>
-- Afficher des ressources dans le cartouche (la barre fixe du lecteur).
-- La quantité se met à jour toute seule quand on prend / lâche / consomme / crée.
Le campement est un lieu.

-- « possédé » (périmètre par défaut) : ce que le joueur transporte.
L'or est une ressource exprimée en pièces.
L'or est affiché en haut à droite.
Il y a 12 pièces d'or ici.

-- « disponible » : tout SAUF l'inventaire du joueur (ici, le bois posé dans le lieu).
Le bois est une ressource.
Le bois disponible est affiché en haut à gauche.
Il y a 20 unités de bois ici.
</file>

[[djnc>wiki_ressources_cartouche|tester cet exemple]] — tapez ''prendre les pièces'' : le compteur d’or (à droite) grimpe à 12 tandis que le bois disponible (à gauche) reste à 20.

<WRAP info>Le périmètre est **direct** (comme ''consommer'') : une pile rangée dans un sac que le joueur porte compte comme ''disponible'', pas comme ''possédé''.</WRAP>

===== Désambiguïsation par emplacement =====

Quand plusieurs piles de la **même** ressource ont été aperçues, une commande non qualifiée (« prendre les pièces ») demande au joueur de préciser, en listant l’**emplacement** de chaque pile (« sur la table », « dans le coffre », « dans votre inventaire »).

Seules les piles **déjà mentionnées** au joueur sont proposées : on ne révèle pas les piles encore inconnues. S’il n’en reste qu’une après ce filtre, elle est choisie sans poser de question.

===== Exemple complet =====

Un petit campement combinant les trois styles de ressources, l’affichage, les commandes et les instructions :

<file donjon wiki_ressources_campement>
-- ============================================================
--  Exemple complet : « Le campement »
-- ============================================================

Le titre du jeu est "Le campement".

Le campement est un lieu.
Sa description est "Un campement au pied de la montagne : un feu de camp à entretenir, et de quoi tenir la nuit.".

Le feu est un objet ici.

-- de l'or, exprimé en pièces
L'or est une ressource exprimée en pièces.
Il y a 12 pièces d'or ici.

-- du bois (massif) : unité par défaut « unité »
Le bois est une ressource.
Il y a 20 unités de bois ici.

-- des rations, comptées par leur nom, que l'on peut manger
Les rations sont une ressource mangeable.
Il y a 4 rations dans le campement.

-- entretenir le feu consomme 5 unités de bois
action alimenter ceci:
  définitions:
    ceci est un objet.
  phase exécution:
    consommer 5 unités de bois.
  phase épilogue:
    dire "Vous jetez 5 unités de bois dans le feu, qui crépite de plus belle.".
fin action

-- une prière fait apparaître quelques pièces d'or dans votre bourse
action invoquer:
  phase exécution:
    créer 3 pièces d'or dans l'inventaire.
  phase épilogue:
    dire "Trois pièces d'or tintent dans votre bourse.".
fin action
</file>

[[djnc>wiki_ressources_campement|tester cet exemple]] — essayez ''regarder'', ''alimenter le feu'' (il reste 15 unités de bois), ''invoquer'', ''prendre les rations'' puis ''manger 2 rations''.

===== Voir aussi =====

  * [[reference:definitions:objets|Objets]] — le type de base dont héritent les ressources
  * [[reference:definitions:classes|Classes et états]]
  * [[reference:instructions:deplacer|Instruction déplacer]]

{{tag>ressource ressources quantite quantité quantifiable multiple unite unité pile piles or argent bois consommer creer créer cartouche objet_multiple}}