# ENT1 — architecture et logique game-specific

## Positionnement

ENT1 est un jeu By Year centré sur une entreprise qui combine production, usines, matières premières, ressources humaines, financement et lancement de produits sur plusieurs pays. Le framework annuel reste commun; les décisions et calculs ENT1 vivent sous `GameSpecific/ent1` et `server_scripts/ent1`.

## Static data

`exports/exportAllData.js` associe ENT1 aux datasets suivants : scenario, salary, employees, raw\_mat, factories, product\_specs, comms, distrib, medias, events, price\_specs, segments, countries et act\_perf\_pond, plus `constants`.

## Modèles Unity

<table id="bkmrk-domaineclasses-princ"><thead><tr><th>Domaine</th><th>Classes principales</th></tr></thead><tbody><tr><td>Production</td><td>`Factory`, `FactoryData`, `RawMatData`, `ProductionResult`</td></tr><tr><td>Produits/marché</td><td>`ProductSpecs`, `LaunchedProduct`, `Market`, `Country`, `DistribData`, `MediaData`, `CommTool`</td></tr><tr><td>RH</td><td>`EmployeesData`, `SalaryData`, `ResignationResult`</td></tr><tr><td>Résultats</td><td>`Results`, `LaunchProductSales`, `LaunchProductScores`, `Ratio`</td></tr><tr><td>Runtime</td><td>`TeamDecisionsEnt1`, `TeamEnt1`, `YearData`</td></tr></tbody></table>

## Commandes métier serveur

`ent1_utils_custom_command.js` couvre notamment :

- création/suppression/lancement de produit;
- construction et vente d'usine;
- achat de matières premières;
- affectation de production d'usine;
- embauche/licenciement;
- salaire;
- prêt/financement.

## Génération des résultats

```mermaid
flowchart TD
DEC[Décisions équipes] --> PROD[Usines + matières premières]
DEC --> HR[Employés + salaires]
DEC --> LP[Produits lancés]
PROD --> CAP[Capacité / production]
HR --> CAP
LP --> MARKET[Marché par pays/segment]
CAP --> SALES[Ventes]
MARKET --> SALES
SALES --> FIN[Cash / résultats]
FIN --> SCORE[Scores + ratios + rankings]

```

`GenerateResultsEnt1` rassemble produits et usines, calcule moyennes, démissions, production, scores et ventes, puis finalise les équipes et sauvegarde les résultats.

## Bots

`BotsEnt1` peut décider prêts, production souhaitée, construction d'usines, employés, choix de pays, matières premières et création de produits. Il est utilisé dans les simulations async.

## UI

Les écrans game-specific sont sous `Assets/GameSpecific/ent1/Src/UI` : usines, production, raw materials, RH, salaires, finance, pays, portfolio, lancement produit, marché, rapports et checklists.

## Debug

Pour un résultat ENT1 incorrect, suivre : custom command → `TeamDecisionsEnt1` → `GenerateResultsEnt1` → `Results`. Pour une incohérence de production, inspecter ensemble factories, raw mats, employés et la quantité réellement lancée.

## Ajouter une feature ENT1 de A à Z

ENT1 croise plusieurs sous-systèmes; une décision peut affecter production, matières premières, employés, cash, produits et ventes. Avant de coder, identifier laquelle de ces chaînes la feature modifie.

### Carte serveur à connaître

<table id="bkmrk-zone-fonctions-cl%C3%A9s-"><thead><tr><th>Zone</th><th>Fonctions clés</th></tr></thead><tbody><tr><td>Cycle/état</td><td>`startYearGameSpec`, `getYearData`, `generateEvents`, `anyDecisionsTaken`.</td></tr><tr><td>Usines / production</td><td>`getTotalFactoryCost`, `getNeededRawMats`, `SetProductionsForProduct`, `computeFactoriesProduction`.</td></tr><tr><td>RH</td><td>`getNumEmployees`, `computeSalaryAverages`, `computeResignations`.</td></tr><tr><td>Marché</td><td>`gatherProducts`, `computeProductAverages`, `computeScores`, `generateSales`.</td></tr><tr><td>Fin de génération</td><td>`finalizeTeamsData`, `saveResults`, `resetTeam`, `deleteResults`.</td></tr></tbody></table>

### Custom commands ENT1 existantes

Le fichier `ent1_utils_custom_command.js` gère notamment `saveLaunch`, `deleteLaunch`, `buildFactory`, `sellFactory`, `buyRawMats`, `setFactoryProduction`, `hireEmployees`, `dismissEmployees`, `setEmployeeSalary` et `updateLoan`.

### Procédure pour une nouvelle décision

1. Ajouter la static data si la décision dépend d'un coût/capacité/pays/employee.
2. Ajouter le champ au `YearData`/`TeamDecisionsEnt1`.
3. Ajouter l'UI dans le domaine approprié : factory, HR, finance, product/market.
4. Ajouter la command et valider cash/capacité côté serveur.
5. Envoyer un message ENT1 et mettre à jour `TeamControllerEnt1`.
6. Consommer la décision dans la bonne phase de `GenerateResultsEnt1`.
7. Si l'état survit à l'année, mettre à jour `finalizeTeamsData/resetTeam`.
8. Si score/ratio change, mettre à jour Eval/rankings/report.
9. Si bots supportés, ajouter la décision dans `BotsEnt1`.
10. Tester reopen year.

## Piège principal : dépendances physiques

Une décision de lancement produit peut être impossible même si le produit est valide : il faut production disponible, usines, matières premières et employés. Les validations UI ne remplacent jamais celles côté serveur.

## Debug génération ENT1

1. team decisions;
2. factories + raw mats;
3. employees/salaries;
4. production calculée;
5. products gathered;
6. averages/scores;
7. sales;
8. cash/ratios finalisés;
9. Results Unity/report.