Encyclopédie & Wiki Flatland

> Page d'accueil / Landing Page : /

> Dépôts Sources: flws (Backend) · flws-web (Client Web) · flws-page (Page Vitrine)

> Développé par Long Phan ([email protected] · Démo : /demo/)

> Conçu et perfectionné avec OpenCode & Antigravity · Développé à partir des concepts fondamentaux de l'œuvre classique d'*Edwin A. Abbott, Flatland: A Romance of Many Dimensions*** (1884).

Flatland est une simulation autonome de vie artificielle et d'écosystème en 2D, conçue d'après les idées mathématiques et spatiales d'Edwin A. Abbott.

Philosophie de conception

Ce projet est développé à partir de l'idée de Flatland plutôt que d'imiter servilement le livre. Il adopte les postulats d'Abbott — contraintes du plan 2D, hiérarchie géométrique selon le nombre de sommets, perception atmosphérique et regard depuis une dimension supérieure — pour fonder un écosystème de vie artificielle évolutif et organique qui se métamorphose au fil du temps.

Architecture et systèmes fondamentaux

• La Sphère (Modèle divin) : La Sphère établit les lois universelles de la nature (capacité de charge, croissance végétale, métabolisme, maladies, climat) depuis Spaceland (l'espace tridimensionnel), sans jamais intervenir arbitrairement dans les existences individuelles. Paramétrable via un sélecteur de 🎯 Préréglages et 6 ⚖️ Domaines Macro avec recherche en temps réel et doubles curseurs. Les organismes se repèrent grâce à 16 capteurs de rayons et des actionneurs neuronaux Micro-RNN.
• Écologie botanique & Nutrition fonctionnelle : 6 espèces végétales distinctes (herbe, grain, baie, herbe_médicinale, champignon, toxique) dotées de densités caloriques propres, de cycles de flétrissement, d'effets curatifs et d'orientations alimentaires selon l'état de santé.
• Agence cognitive & Intelligence sociale des clans : Une IA d'utilité multi-objectifs remplace les arbres conditionnels rigides ; cartographie mentale par jalons spatiaux ; phalanges tactiques de soldats, manœuvres d'évitement des femmes-lignes, formation de binômes de confiance, tableaux de tâches claniques autonomes, régimes politiques variés (Monarchie, Théocratie, Junte, République), décrets d'urgence (rationnement hivernal, loi martiale), caravanes de commerce et fêtes automnales des moissons.
• Évolution autonome & Culture : 6 archétypes de personnalité héréditaires (brave, prudent, altruiste, avare, explorateur, bâtisseur), fabrication d'outils (lances, paniers, cataplasmes, couronnes), 4 compétences d'élite (Agriculture 🌾, Combat ⚔️, Cueillette 🦴, Soins 🌿), titres honorifiques dynamiques, transmission orale des aînés aux jeunes dans les demeures et bulles de pensées en direct.
• Métabolisme & Dynamique énergétique réalistes : Faible dépense chez les nouveau-nés ($0.45\times$), coût d'endurance au combat et gestion de réserves portatives via des paniers.
• Colonies & Diplomatie : Bâtisses closes avec portes ajustées, territoires multi-maisons, greniers communautaires, coalitions de défense mutuelle, tributs et scissions claniques.
• Physique géométrique & Évolution morphologique (K∈[3,24]) : Génomes polaires $(r_i,\phi_i)$ $K\in[3,24]$ (KMAX 24, morphology_engine.py) avec calcul des propriétés physiques SoA ($A,P,I_{zz},\theta_{\min},asym,D_{mult}$) et détection fine SAT ; le recuit morphologique $\lambda(g)$ assure la transition des gabarits d'Abbott vers une spéciation libre, parade nuptiale neuronale et sauvegardes contre l'extinction ($\eta(N)$, miracles de la Genèse).
• Miroir Génomique Évolutif : Rendu visuel phénotypique dynamique où le corps, la corolle et la luminescence de chaque créature reflètent son génome vivant, sa profondeur générationnelle (Gén 0 → 2000+) et ses mutations physiques à travers les millénaires.
• Synchronisation en temps réel : Moteur déterministe diffusant l'état du monde via WebSocket (/ws) à ~30–60 FPS avec persistance historique sur SQLite.

Flatland : Le Roman vs. La Simulation

Étude comparative entre le classique satirique d'*Edwin A. Abbott (1884), Flatland: A Romance of Many Dimensions*** et cette simulation autonome de vie artificielle.

---

1. Castes, Géométrie & Hiérarchie Sociale

| Dimension | Livre d'Abbott (Flatland, 1884) | Notre Simulation (Flatland Simulator) |

| :--- | :--- | :--- |

| Principe hiérarchique | "La configuration fait l'homme." Le rang social est strictement déterminé par le nombre de côtés et la régularité des angles. | Les entités héritent de castes géométriques précises basées sur leur nombre de sommets (N-gones) et leur régularité. |

| Femmes (Lignes) | Lignes droites sans épaisseur angulaire. Invisibles de face et acérées comme des lames, elles doivent émettre un cri de paix continu et emprunter des portes dédiées. | Représentées comme des segments 1D (shape: 'line'). Remarquablement agiles, avec une dynamique de déplacement et d'abri spécifique. |

| Ouvriers / Soldats | Triangles isocèles aux angles sommitaux étroits et tranchants (dangereux, instables, enclins aux révoltes). | Soldats (#ff7b72) : Combattants aux attaques perçantes, discipline martiale et patrouilles défensives aux frontières. |

| Artisans & Classe moyenne | Triangles équilatéraux (3 côtés égaux) — marchands et travailleurs respectables et stables. | Artisans (3–4 côtés, #f2cc60) : Fermiers, cueilleurs et bâtisseurs chargés des récoltes et de l'entretien des demeures. |

| Gentlemen & Professionnels | Carrés (4 côtés) et Pentagones (5 côtés) — classes administratives et bourgeoises dirigeantes. | Gentlemen (4 côtés, #ffa657) et Professionnels (5 côtés, #d2a8ff) : Rôles d'administration et de gestion spécialisée. |

| Noblesse | Hexagones (6 côtés) et polygones supérieurs — aristocrates et hommes d'État influents. | Nobles (6–8 côtés, #79c0ff) : Haute influence et priorité dans la pérennité de la lignée. |

| Clergé (Cercles) | Polygones aux sommets si innombrables (≥ 24 à plusieurs centaines) qu'ils forment des cercles parfaits. Dirigent religion et morale. | Prêtres (≥ 24 côtés, #e6edf3) : Émettent une aura apaisante, soignent leurs alliés et résistent naturellement aux épidémies. |

---

2. La "Loi de la Nature" & L'Ascension Générationnelle

• Dans le Livre :

- Abbott pose la "Loi du Progrès Ascendant" : Le fils d'un polygone régulier gagne presque toujours un côté de plus que son père (un Carré engendre un Pentagone, dont le fils sera Hexagone), élevant la lignée vers la perfection circulaire.

- Les rares "Irréguliers" (aux angles asymétriques) sont perçus comme une menace publique et enfermés ou éliminés.

• Dans l'Application :

- Évolution générationnelle : La progéniture hérite des traits ancestraux avec une probabilité d'accroissement (sides += 1), illustrant l'ascension historique vers le cercle.

- Irrégularité & Déclassement : Les entités développant des mutations asymétriques voient leur anomalie mesurée et signalée visuellement.

- Généalogie dynastique : L'arbre généalogique retrace pères, mères et filiations sur des décennies d'histoire du monde.

---

3. Reconnaissance Visuelle, Météo & Perception

• Dans le Livre :

- Dans un monde 2D, tous les habitants ressemblent vus de profil à de simples lignes !

- Dans le Sud Brumeux, les Flatlandais pratiquent la "Reconnaissance Visuelle" — estimant l'angle et la distance d'un polygone selon la rapidité avec laquelle ses bords se fondent dans le brouillard.

- Dans le Nord Clair, ils doivent recourir au "Palper" (toucher les sommets du bout des doigts).

• Dans l'Application :

- Moteur météo dynamique : Alterne entre Ciel dégagé, Brouillard, Pluie et Tempête.

- Vision atmosphérique : La brume et les orages réduisent drastiquement le champ visuel des créatures, les obligeant à se fier aux alarmes acoustiques de proximité.

- Cycle Jour/Nuit : La luminosité varie de l'aube au crépuscule jusqu'à l'obscurité totale, guidant les créatures vers la sécurité de leurs foyers.

---

4. Habitats, Colonies & Architecture Territoriale

• Dans le Livre :

- Les maisons sont obligatoirement pentagonales ou hexagonales, avec des entrées distinctes pour les femmes et les hommes.

• Dans l'Application :

- Économie coloniale : Les maisons sont des bâtisses 2D concrètes avec portes orientées (nord, est, sud, ouest) et nombre de lits limité.

- Demeure Principale Unique : Chaque clan fonde exactement une Demeure Principale / QG (siège du chef) entourée d'abris secondaires.

- Fonction du refuge : Les créatures y dorment la nuit, s'y protègent des gelées d'hiver, s'y soignent et y éduquent leurs petits.

- Navigation de franchissement : Les créatures calculent des points de passage fluides pour franchir les seuils sans rester bloquées contre les parois.

---

5. Diplomatie de Clan, Totems & Société Évolutive

Au-delà de l'État victorien centralisé d'Abbott, l'application met en scène une société évolutive vivante :

• Totems & Spécialisation : Vénération de l'un des 8 Avatars Sacrés de la Sphère (⭕ Radiant Circle, ⚡ Celestial Strike, 👁️ All-Seeing Vertex, 🛡️ Indomitable Monolith, 🌿 Sacred Spiral, ⚖️ Cosmic Scales, 🌀 Dimensional Rift, 🕯️ Eternal Hearth), orientant les vocations du clan.
• Diplomatie, Tributs & Conflits : Relations mouvantes entre clans incluant traités, guerres de conquête, pillages de greniers et scissions.
• Autonomie individuelle : Tempéraments personnalisés (Brave, Prudent, Altruiste, Avare, Explorateur, Bâtisseur) dotés de paniers individuels et d'outils façonnés.

---

6. La Dimension Supérieure : L'Utilisateur est "La Sphère"

Le lien le plus fondamental entre le livre et l'application réside dans le statut de l'utilisateur :

• Dans Flatland, le protagoniste A Square reçoit la visite d'une Sphère venue de Spaceland, capable de contempler le monde depuis l'axe vertical, de voir à travers les portes closes et de modifier l'univers 2D avec une toute-puissance céleste.
• Dans notre Application :

- Vous êtes La Sphère (Dieu) : Devant votre écran, vous observez Flatland depuis la troisième dimension.

- Le Panneau de La Sphère : Vous détenez le pouvoir de réécrire les "Lois de la Nature" en direct — déclencher des famines, moduler la fertilité, éradiquer ou propager les fléaux et guider les clans vers la gloire.

Configuration & Exploitation

Variables d'environnement (FLATWORLD_*)

| Variable | Défaut | Description |

|---|---|---|

| FLATWORLD_WIDTH | 400 | Largeur du monde (unités de grille) |

| FLATWORLD_HEIGHT | 300 | Hauteur du monde |

| FLATWORLD_BOUNDARY | wrap | Bordure torique continue (wrap) ou mur hermétique (clamp) |

| FLATWORLD_SEED | 42 | Graine pseudo-aléatoire du monde |

| FLATWORLD_TICK_RATE | 10 | Fréquence de calcul en ticks par seconde |

| FLATWORLD_DB | backend/flatworld.db | Chemin de la base de données SQLite |

| FLATWORLD_GOD_KEY | — | Clé secrète divine définie au démarrage |

Clé secrète divine (Authentification)

Les commandes POST /api/laws, POST /api/presets/{name}, POST /api/control et les ordres de contrôle WebSocket requièrent l'en-tête d'authentification divine (X-God-Key ou le champ key du socket). Si aucune clé n'est encore configurée, le serveur renvoie une erreur 409 et l'interface invite à en définir une (POST /api/auth/setup). En cas d'oubli, la réinitialisation s'effectue sur le serveur : cd backend && uv run python -m app.godkey reset <nouvelle_clé>. Seul un hachage cryptographique sécurisé PBKDF2 est conservé.

Persistance des données (db.py:20)

Base SQLite flatworld.db en mode journalisé WAL avec verrou réentrant thread-safe. Tables principales :

• worlds : Cycles d'existence des mondes (graine, dimensions, horodatages).
• events : Registre historique des événements (naissances, décès, guerres, épidémies).
• law_changes : Journal des modifications de lois par la Sphère.
• creatures : Lignées généalogiques complètes de chaque citoyen.
• snapshots : Instantanés de sauvegarde permettant de restaurer le monde après redémarrage.

Architecture des threads & Moteur SimEngine

Le cœur de calcul est rigoureusement déterministe : une seule graine pseudo-aléatoire ordonnée tick par tick. Uvicorn doit être exécuté avec 1 seul processus worker. Avec le moteur SimEngine (main.py:446), l'avancement de la simulation s'exécute sur son propre thread OS dédié, découplé de la boucle asyncio. Le calcul du tick s'opère sous RT.lock tandis que la sérialisation JSON des instantanés s'effectue hors verrou (advance_world_lockless), évitant tout blocage des requêtes REST. Points d'accès d'exploitation :

• GET /healthz — Santé globale du serveur, TPS réel, consommation mémoire, temps de service et clients connectés.
• GET /api/perf/telemetry — Télémétrie de performance : temps de calcul par tick, attente de verrou et latence réseau.
• GET /api/analytics/summary — Synthèse macroscopique démographique, biomasse et distribution trophique.

Fonctionnement du monde Flatland

La Sphère (Modèle divin) : La Sphère (Dieu tridimensionnel) édicte les lois naturelles depuis Spaceland et n'intervient jamais directement sur le destin d'un être individuel. Tout le reste émerge spontanément.

Le tick déterministe

s = Simulation(Config(seed)) → s.step() est rigoureusement déterministe (un seul générateur pseudo-aléatoire random.Random par monde). Une même graine produit toujours le même univers. Ordre d'exécution de chaque tick (backend/app/simulation/core.py Simulation.step()) : météo → croissance végétale → mise à jour spatiale → action des créatures → propagation des maladies → combats et guerres → reproduction → relations diplomatiques → régulation des plantes → décomposition des cadavres → colonies → incrément tick+=1. Le moteur s'exécute sur un thread dédié (SimEngine) avec sérialisation sans verrou (lockless), diffusant les instantanés via WebSocket state à chaque tick.

Cycle de vie & Stades de développement (§A)

L'âge en ticks s'additionne à l'espérance de vie propre à chaque caste (de 4 800 ticks pour une Femme à 9 000 ticks pour un Prêtre). Les stades se divisent selon le ratio âge/longévité : Nourrisson (<15 %), Juvénile (<30 %), Adulte (<75 %), Aîné (≥75 %). L'âge influe sur la vitesse et la portée visuelle (nourrisson 0.6×, aîné 0.85×) ainsi que sur la fertilité (aîné ×0.5). Les causes de trépas sont : starvation (inanition), old_age (vieillesse), euthanasia (purge d'irrégularité), et disease (maladie).

Noyau de vitalité (§AT-4 H-0)

La vie (PV) est une ressource dynamique et non une constante. La régénération exige un excédent calorique : sous 40 % de l'énergie maximale (HEALTH_REGEN_MIN_ENERGY), les plaies cessent de cicatriser, éveillé comme endormi. Le repos abrité soigne à raison de 0.15×rest_recovery_mult, tandis que la guérison éveillée est de 0.1/tick. Sous 20 % d'énergie, l'organisme s'autocannibale : perte de −0.05 PV/tick (HEALTH_SELF_DRAIN_*) jusqu'à ce que mort s'ensuive. L'affaiblissement ralentit l'allure (HEALTH_SPEED_TIERS) : PV <80 vitesse ×0.95, <60 ×0.85, <40 ×0.70, <20 ×0.50. Les corps malades ne peuvent procréer : l'accouplement requiert health ≥ REPRO_MIN_HEALTH (50 PV), freinant les naissances lors d'une épidémie sans altérer les lois de fertilité.

Variété des blessures & Économie des soins (§AT-4 H-1)

La faim chronique ronge : rester sous 20 % d'énergie plus de 30 ticks draine 0.08 PV/tick (cause exhaustion). La vieillesse use : les aînés perdent passivement 0.02 PV/tick. La maladie trouble le regard et émousse les récoltes (−20 % de cueillette sous 60 PV, −50 % sous 30 PV). Les blessés graves (<30 PV) n'engagent jamais de duel. Les coups violents (>15 dégâts) infligent une blessure persistante (50 à 100 ticks) diminuant de moitié les soins et entravant l'allure. L'emplacement physique est déterminant : soigner en extérieur n'est efficace qu'à 50 % comparativement à 80 % dans une maison et 100 % durant le sommeil abrité. Les baies soignent +0.3 PV/tick pendant 20 ticks, les céréales +0.2 PV sur 30 ticks et les herbes médicinales +0.8 PV sur 40 ticks.

Axiomes physiques (§AQ PH-0)

L'énergie est la monnaie universelle de Flatland. La lumière solaire est l'unique apport d'énergie : la fonction _sun_factor() suit le cycle solaire (nulle la nuit, maximale à midi) et gouverne la photosynthèse et la dispersion des graines. Chaque créature paye un entretien métabolique selon sa complexité géométrique (METABOLIC_COST) : triangles 1.0×, carrés 1.1×, pentagones 1.2×, hexagones et nobles 1.3×, femmes et prêtres 1.5×. Cicatriser consomme de l'énergie : chaque point de vie régénéré coûte 0.5 unité d'énergie.

Thermodynamique & Température corporelle (§AQ PH-1)

Une grille thermique de 25 unités relaxe chaque tick vers la température saisonnière (Printemps 12°C / Été 24°C / Automne 8°C / Hiver −4°C), animée par des fronts froids venant de l'ouest et chauds de l'est, les variations nycthémérales (±5°C), les intempéries (pluie −2°C, orage −3°C) et la chaleur des feux (+60°C dans un rayon de 8 unités). Les corps s'équilibrent thermiquement avec leur milieu. Les demeures de paille, bois ou pierre isolent les résidents vers un climat tempéré de 18°C. Dépasser 36°C entraîne une hyperthermie fatale ; chuter sous 2°C provoque une hypothermie sévère.

Vent & Propagation du feu (§AQ PH-2)

Le vent souffle selon un vecteur dynamique (wind_angle/wind_speed) influencé par la météo : brise calme 0.25, averse 0.55, rafales de tempête 1.0. Le feu suit rigoureusement le vent : propagation et allumage sont multipliés dans le sens du vent, emportant les taillis sous le vent à grande vitesse.

Hérédité des lois naturelles (§B)

Dimorphisme : les polygones sont mâles, les segments de droite sont femelles. Les fils héritent du nombre de côtés du père plus un : côtés = père + 1, plafonné à 24 côtés (devenant ainsi un Prêtre quasi-circulaire). Les filles demeurent des segments unidimensionnels. Les mutations introduisent des asymétries (irregularity). Les triangles isocèles voient leur angle au sommet croître de 0.5° par génération ; à 60°, ils deviennent équilatéraux et sont anoblis en Artisans. Le moteur morphologique polarisé $(r_i,\phi_i)$ simule les transitions organiques continues.

Moteur de morphologie & Physique géométrique (K∈[3,24])

Génome sous forme vectorisée SoA comprenant rayons polaires, angles, superficie, périmètre, moment d'inertie $I_{zz}$ et asymétrie. Les attributs physiques modulent la capacité énergétique, l'impulsion motrice et la force de frappe lors des collisions SAT. Le protocole de clémence (safeguard_morph_mercy) suspend l'euthanasie lorsque la population s'effondre.

Histoire du Monde, Chroniques & Récits par IA (§BM)

Flatland propose une suite historiographique, analytique et de génération de récits par IA :

• Moments Majeurs & Saut Temporel : Les 5 jours les plus tumultueux (pertes, conquêtes, schismes) sont mis en avant au-dessus du flux chronologique. Possibilité de sauter instantanément à n'importe quel tick précis.
• Barre d'Époques & Courbe Démographique : Navigation fluide à travers les ères de Flatland (Genèse, Âge des Tribus, Époque Féodale, Zénith Classique, Ère de Ruine) superposée d'indicateurs de conflits et de pandémies.
• Panthéon des Records & Légendes : Classement historique des plus grandes victoires, du jour le plus meurtrier, du royaume le plus peuplé, des architectes divins et des héros/antagonistes célèbres.
• Analyses Historiques : Matrice thermique des rivalités claniques, répartition des causes de mortalité par ères de 10 jours et indice de foi au fil du temps.
• Générateur de Récits IA Intégré : Rédaction directe de sagas littéraires via Gemini 1.5 Flash ou OpenAI GPT-4o-mini avec clés API stockées localement dans le navigateur.
• Liens Profonds & Carte de Partage : URLs partageables avec ?history=42 ou ?clan=7 et exportation de cartes récapitulatives haute résolution 1200×630 au format PNG.

Hiérarchie des castes & Irrégularité (§C)

À l'âge adulte, toute créature dont l'asymétrie excède le seuil de conformité est bannie ou euthanasiée pour préserver l'ordre géométrique d'Abbott. Les déviations légères entraînent une rétrogradation dans la caste militaire des Soldats.

Épidémies & Contagion (§D)

Les maladies émergent spontanément selon un taux d'éclosion, se transmettent par proximité (propagation accrue de 50 % en hiver), consument l'énergie et drainent les points de vie. L'organisme peut guérir grâce à son immunité naturelle ou en absorbant des herbes de soin.

Environnement & Saisons (§E)

Rythme cadencé par le jour et la nuit ainsi que par les quatre saisons. L'obscurité nocturne et le brouillard réduisent considérablement la vue. Les saisons modulent la flore : Printemps (flore 1.0×, natalité +25 %), Été (flore 1.2×), Automne (flore 1.0×), Hiver (flore 0.5×, morbidité épidémique +50 %).

Clans & Organisation sociale (§C/I/P/V)

Chaque maison permanente fonde un clan autonome mené par la créature la plus proche de son foyer. Les descendants héritent du clan de leur mère. Les clans vénèrent l'un des 8 Avatars Sacrés de la Sphère conférant des bénédictions uniques (Cercle Rayonnant, Frappe Céleste, Sommet Omniscient, Monolithe Indomptable, Spirale Sacrée, Balances Cosmiques, Brèche Dimensionnelle, Foyer Éternel).

Économie alimentaire & Botanique (§H/N/O)

Les plantes germent, mûrissent et dispersent leurs graines à proximité. Les défunts laissent des dépouilles nutritives qui fertilisent le sol environnant. Six espèces végétales coexistent : l'Herbe commune, les Céréales dorées, les Baies revigorantes, les Herbes curatives, les Champignons décomposeurs et les Plantes vénéneuses. Les herbivores sauvages broutent librement et servent de proies aux prédateurs.

Communication & Transmission du savoir (§Q/X)

Les créatures émettent des signaux d'appel au festin ou d'alarme. L'expérience acquise (points d'eau et de cueillette, dangers, abris sûrs, clans ennemis) est mémorisée et partagée lors des interactions de groupe. Tout individu agressé appelle à l'aide, mobilisant les guerriers alliés dans le périmètre.

Géopolitique & Alliances (§AB)

Les clans bienveillants forgent des pactes de défense mutuelle, partagent leurs greniers à provisions ou soumettent des clans rivaux au versement de tributs réguliers. Les chefs belliqueux déclarent des guerres territoriales tandis que les pacificateurs négocient des trêves en période de disette.

Cannibalisme de désespoir (§AC)

Lorsque la famine menace l'existence même de la colonie et que l'énergie chute à zéro, la loi de la faim pousse les plus désespérés à dévorer les blessés ou les captifs ennemis. Cet acte odieux entraîne le bannissement immédiat du transgresseur, créant une lignée de parias impitoyables.

Décomposition naturelle (§AE)

Les végétaux arrivés au terme de leur existence flétrissent, brunissent et restituent leurs nutriments au terreau avant de s'effacer, laissant le champ libre à une nouvelle génération de pousses vivaces.

Habitats & Colonies (§L/N)

Les maisons de pierre, de bois ou de chaume offrent un refuge contre les intempéries et les rigueurs de la nuit. Leurs portes étroites laissent passer les citoyens tout en barrant l'accès aux féroces carnivores sauvages.

Évolution autonome & Outils (§AG)

Les citoyens développent des tempéraments héréditaires (brave, prudent, altruiste, avare, explorateur, bâtisseur). Ils confectionnent et s'équipent d'outils : lances militaires, paniers de récolte, onguents de soin et couronnes royales, tout en se perfectionnant dans quatre métiers essentiels.

Métabolisme par stade & Endurance (§AH)

Les dépenses caloriques s'adaptent à l'âge : les nourrissons dépensent 55 % d'énergie en moins, les juvéniles 25 % en moins. Les affrontements guerriers épuisent la vigueur ; la fatigue réduit la force des coups de 30 %.

Intelligence collective Utility AI (§AL)

Le système d'intelligence artificielle à utilités multiples évalue en temps réel les impératifs de survie, les devoirs de caste et les signaux d'urgence. Les créatures établissent une carte mentale de leur territoire et adoptent des formations tactiques disciplinées en temps de guerre.

Écologie botanique & Diététique (§AM)

Les Céréales apportent un apport calorique durable ; les Baies procurent une poussée d'accélération ; les Herbes purifient les infections ; les Champignons prospèrent sur les décombres et bravant le gel hivernal.

Interface terminale TUI (§AI)

Une console Textual complète s'arrime à l'univers en cours d'exécution, permettant de suivre chaque sujet, d'examiner le registre historique et d'ajuster les lois physiques en direct.

Moteur neuronal Elman & Évolution continue (BA)

Chaque individu est doté d'un réseau récurrent Elman RNN autonome (16 entrées sensorielles → 12 neurones cachés → 7 sorties motrices régies par 295 poids float32). Cadencé à 15 Hz, il traite raycasts géométriques, sons et effluves pour s'adapter à son environnement et transmettre ses acquis aux générations futures.

Durabilité — Équilibre Multi-Générationnel

Le monde maintient son équilibre sur des centaines de jours et permet l'essor de dynasties prospères grâce à une homéostasie écologique et sociale finement ajustée.

Préréglages Sélectionnés

• balance ⚖️ (Défaut) — Équilibre idéal calibré pour 200 à 350 habitants avec 380 unités de nourriture, capacité de 400 (max 500), guerres modérées, prédation rare, agriculture, amortissement de densité ($\xi$), sauvegarde contre l'extinction ($\eta$) et clans florissants.
• sustainable 🌿 — 1000 jours de paix prospère : nourriture abondante (550), capacité de charge 550 (max 600), greniers remplis, fêtes des moissons, banquets et amortissement doux.
• theocracy 🔮 — L'Ère de la Sphère : avatars sacrés, temples lumineux, miracles, épiphanies 3D, conciles sacrés et dîmes pieuses.
• warlords ⚔️ — L'affrontement des seigneurs : conquêtes impériales, pillages de greniers, prises de demeures, expansion territoriale et coalitions défensives.
• chaos 🔥 — Forte proportion de prédateurs, guerres meurtrières, incendies, séismes, épidémies fréquentes et saisons rapides.
• extinction 💀 — Famine sévère (120 nourriture), hivers rigoureux (0.30×), forte usure en extérieur, éprouvant la résistance sociétale face à l'effondrement.
• boom 🚀 — Reproduction effrénée, 440 nourriture, capacité de 800 (max 850) pour tester de gigantesques métropoles.

Utilisation : curl -X POST localhost:8000/api/presets/balance?reset=true ou via le panneau de La Sphère.

Homéostasie Dynamique & Prévention de l'Extinction

Flatland intègre deux moteurs de rétroaction homéostatique en boucle fermée :

1. Amortissement Souple lié à la Densité ($\xi$)

Quand la population $N$ excède la capacité de charge $K_{cap}$, le ratio $\xi = (N - K_{cap}) / K_{cap}$ freine la surpopulation de façon non-linéaire :

• Modération des naissances : $R_{birth} = R_0 / (1 + \text{damping\_steepness} \cdot \xi^2)$
• Stress métabolique de surpeuplement : $M_{decay} = M_0 \cdot (1 + \text{crowding\_stress\_mult} \cdot \xi)$
• Tension sur les ressources : La régénération végétale ralentit proportionnellement à la saturation du milieu.

2. Sauvegardes d'Extinction & Miracles de la Genèse ($\eta$)

Lorsque la population chute sous le seuil d'alerte $K_{safe} = K_{cap} \times \text{safeguard\_relief\_ratio}$, des mesures d'urgence se déclenchent :

• Niveau 1 ($\eta \le 0.5$) : Secours anti-famine, dépense métabolique allégée jusqu'à 40%, accélération de la pousse végétale de 60%.
• Niveau 2 ($\eta > 0.5$) : Urgence critique, délai de reproduction réduit de moitié, suspension de l'euthanasie des difformes (safeguard_morph_mercy).
• Niveau 3 ($N \le K_{crit}$) : La Sphère opère un Miracle de la Genèse, créant un groupe safeguard_genesis_batch d'êtres réguliers pour perpétuer l'espèce.

Performance & Échelle — Plus de 1000 individus @ 60 FPS

• Hachage Spatial sans Allocation : Une grille 1D pré-allouée dans world.py supprime les allocations de tuples et le re-hachage à chaque tick ; query_radius emploie un test de distance au carré sans math.hypot.
• Recherche Rapide de Partenaires : La recherche de partenaires via l'index spatial s'effectue en $O(1)$ au lieu d'un balayage quadratique $O(N^2)$.
• Mise en Cache des Instantanés : Le décor statique et les obstacles sont mis en cache, supprimant la duplication inutile de listes à chaque trame diffusée.
• Rendu Groupé Canvas 2D : Regroupement des passes de dessin par caste, plante et structure avec transformations trigonométriques directes, éliminant le coût de ctx.save() / ctx.restore() par individu (appels de tracé réduits de plus de 20 000 à ~30-50).
• Niveau de Détail Dynamique (LOD) : L'affichage adapte les détails selon le zoom (omission des glyphes fins en vue éloignée), assurant un 60 FPS constant même en forte densité.
• État React Découplé : Le flux haute fréquence alimente directement des références mutables à 60 FPS pour le Canvas, tandis que le rafraîchissement React (HUD, graphiques) est régulé à ~6 Hz pour préserver la fluidité de l'interface.

Carte du code source

Architecture Tri-Dépôts & Déploiement Unifié (§BP)

Flatland est découplé en trois dépôts GitHub spécialisés avec déploiement unifié sur le même système :

• flws (github.com/longphanmn/flws) : Moteur de simulation backend pur (FastAPI, thread SimEngine, SoA NumPy, micro-Elman RNN, physique SAT polaire, TUI, SQLite WAL). Écoute sur le port hôte :8000.
• flws-web (github.com/longphanmn/flws-web) : Client web frontend autonome (React 18, Vite, TypeScript, Canvas2D/WebGL 60 FPS, Observatoire macroscopique). Déployé sur GitHub Pages (https://longphanmn.github.io/flws-web/) et écoute sur :5173 / :80 (Nginx reverse-proxy vers backend).
• flws-page (github.com/longphanmn/flws-page) : Page d'accueil et vitrine officielle (canevas interactif, badge sonore synthétisé, mythes). Déployé sur GitHub Pages indépendant (https://longphanmn.github.io/flws-page/).
• Déploiement unifié sur le même système : docker-compose.yml et deploy.sh orchestrent et exécutent simultanément le backend et le frontend sur la même machine hôte.

Architecture Backend (backend/app/)

• config.py:13 — Dataclass Config : Géométrie du monde, densités, nourriture, dépouilles, dynamique de groupe, reproduction, épidémies, météo, abris, maisons et annales. Détection automatique des variables d'environnement via from_env().
• entities.py:1 — Définition des entités fondamentales : CasteTraits, CASTE_TRAITS, YIELD_RANK, caste_name(), Creature (géométrie, côtés, caste, âge, santé, infection, clan, sommeil...), Food (maturation), Corpse (dépouille), House (dimensions, porte, clan).
• world.py:32 — Registre spatial World avec table de hachage spatiale uniforme (cell_size, rebuild_index), calcul des distances toriques et requêtes de voisinage query_radius.
• simulation/ — Moteur de simulation modulaire décomposé (§BI) :

- core.py — Classe maîtresse Simulation, boucle de tick déterministe et synchronisation SoA.

- creature_update.py — Pipeline d'agent en 7 étapes décomposées (_creature_movement, _creature_feeding, etc.).

- settlement.py — Économie de l'habitat, construction, revendications et franchissement des portes.

- lifecycle.py — Génération d'agents, reproduction, naissance, mort, compétences et propagation des épidémies.

- ecology.py — Cycle végétal, agriculture, banquets, décomposition et recyclage des nutriments.

- theology.py — Réserves de foi, 8 Avatars Sacrés, sanctuaires, miracles, synodes et épiphanies.

- society.py — Clans, diplomatie, guerres, coalitions, greniers, caravanes marchandes et cannibalisme.

- serialization.py — Encodage des trames d'instantanés complets et différentiels (deltas).

- environment.py — Météo, dynamique des vents, grille thermique et incendies.

- constants.py — Constantes de simulation, tables de coefficients et générateurs de noms.

• agent_soa.py — Architecture SoA vectorisée pour le traitement en cache de milliers d'agents simultanés.
• agent_pipeline.py — Pipeline de perception par lancer de rayons et physique vectorisée par lots.
• neural_engine.py — Réseau récurrent Elman RNN (16→12→7, 295 poids) pour le contrôle moteur.
• morphology_engine.py — Moteur de morphologie polaire, collisions SAT et calcul des propriétés physiques.
• evolution_manager.py — Recuit morphologique λ(g), gabarits géométriques d'Abbott K3..64 et enjambement polaire.
• spatial_grid.py — Grille spatiale vectorisée pour requêtes de proximité rapides.
• analytics.py — Télémétrie en anneau, métriques macro, démographie et biodiversité.
• safeguard_engine.py — Protocoles de sauvegarde contre l'extinction et Miracles de la Genèse.
• density_damping.py — Amortissement dynamique de surpopulation (ξ).
• auth.py:1 — Dépendance de sécurité FastAPI vérifiant la clé divine par hachage PBKDF2 (X-God-Key).
• protocol.py:7 — Schémas réseau Pydantic : ControlAction, ControlMessage, EntityState, StateMessage, HistoryEvent, HelloMessage, GodLaws.
• db.py:1 — Couche SQLite3 Database optimisée avec WAL, verrous réentrants et écriture différée en arrière-plan.
• main.py:1 — Point d'entrée FastAPI app, moteur dédié SimEngine, diffusion WebSocket Hub, routes REST et /wiki.

Architecture Frontend (frontend/src/)

• App.tsx — Agencement principal de l'application, bandeau HUD, synchronisation WebSocket et volets d'onglets.
• analytics/ — Observatoire & Moteur d'analyses macroscopiques :

- Observatory.tsx — Conteneur plein écran des tableaux de bord analytiques par onglets.

- MacroOverview.tsx — Graphiques étincelles démographiques, santé, biomasse et vitesse.

- SociologyTab.tsx — Hégémonie des clans, caravanes de troc, guerres et successions.

- EcologyTab.tsx — Diversité botanique, régénération des sols et pyramide trophique.

- CrisisTab.tsx — Évolution des épidémies, alertes famines et catastrophes naturelles.

- MutationLab.tsx — Arbre phylogénétique morphologique et nuage de points morphospécifique 2D.

- MetricCard.tsx / Sparkline.tsx — Cartes métriques légères avec visualisations SVG.

• render/CanvasRenderer.tsx — Moteur de rendu HTML5 Canvas à 60 FPS avec tracé vectoriel trigonométrique par lots.
• render/ClanPanel.tsx — Affichage des colonies de clans en temps réel, totems sacrés et états de guerre.
• render/ChronicleFeed.tsx — Fil d'actualité des événements historiques avec filtres contextuels.
• render/PlotsPanel.tsx — Graphiques étincelles (sparklines) de la population, des castes et de la chaîne trophique.
• clan/ClanDetails.tsx — Fiche détaillée du clan, manoir du chef et bilan des pertes au combat.
• history/WorldHistoryModal.tsx — Résumé historique quotidien, grandes guerres et exportation de récit littéraire IA.
• god/GodPanel.tsx — Tiroir interactif des lois de la nature avec 7 préréglages de mondes.
• god/auth.tsx — Boîte de dialogue d'authentification divine et adaptateur de requêtes godFetch.
• inspect/Inspector.tsx — Dossier biologique du citoyen, radar morphologique polaire, constantes et généalogie.
• wiki/Wiki.tsx — Encyclopédie interactive intégrée et banc d'essai d'API.
• types.ts — Interfaces TypeScript calquées sur les schémas du protocole serveur.
• websocket.ts — Client WebSocket à reconnexion automatique résiliente.

Flux de données

SimEngine (thread dédié) → sim.step() → sim.snapshot() (sérialisation sans verrou) → HUB.broadcast → ws → CanvasRenderer + État React App. Client → ControlMessage → apply_control → Mise à jour de la simulation → Journalisation en base. Événements → DB.add_events + Généalogie.

Modèle de données & Protocole réseau

Entités en mémoire vive (In-memory Entities)

• Creature (entities.py:95) : Identifiant id, position x, y, orientation angle, morphologie shape (polygon ou line), nombre de côtés sides, caste sociale caste, rayon radius, âge age, espérance de vie lifespan, stade biologique stage (infant, juvenile, adult, elder), asymétrie irregularity, vitalité health (0–100), infection infected, sexe sex, filiation mother_id/father_id, appartenance clan_id/clan_color, état de repos sleeping/indoors, génération généalogique generation, tick de naissance born_tick, réserve d'énergie energy, statut de faim status.
• Food (entities.py:158) : Coordonnées x, y, stade de maturation végétale growth (de 0.15 à 1.0).
• Corpse (entities.py:170) : Coordonnées x, y, durée de décomposition restante ttl, énergie nutritive energy.
• House (entities.py:184) : Coordonnées x, y, superficie size, largeur de porte door_width, clan propriétaire clan_id/clan_color, statut de ruine is_ruin, dernier assaut hostile takeover_tick.
• Relief et géographie : Zones de terre arable fertile: [{x,y,r}] et rochers infranchissables rocks: [{x,y,r}].

Schémas du protocole réseau (protocol.py)

• EntityState (protocol.py:27) : id, type kind (creature | food | house | corpse), coordonnées x/y, angle, et attributs biologiques optionnels.
• StateMessage (protocol.py:62) : Données complètes diffusées à chaque tick : numéro de tick, graine seed, dimensions width/height/boundary, population totale, ensemble des entités actives, clans, statistiques de mortalité, horloge nycthémérale, saison, météo, matrice diplomatique, événements récents et charge utile analytics à 1 Hz pour l'Observatoire.
• HistoryEvent (protocol.py:86) : Événement chronologique typé : décès, naissance, promotion, épidémie, rémission, floraison, alliance, guerre, assaut de colonie avec horodatage en tick et charge utile payload.
• HelloMessage (protocol.py:99) : Message d'accueil émis à l'ouverture du WebSocket : graine, cadence de tick, et limites du monde.
• ControlMessage (protocol.py:22) : Commande émise par l'utilisateur : action (pause, resume, step, reset, set_speed) accompagnée de son paramètre value.

Flux de synchronisation WebSocket

Serveur vers client : {"type":"hello", ...} à la connexion, suivi de flux continus {"type":"state", ...} à chaque tick d'horloge (intégrant les trames analytics 1 Hz). Client vers serveur : Instructions de régulation divine {"action":"pause"|"resume"|"step"|"reset"|"set_speed", "value":...}.

Lois de la Sphère (The Sphere)

Tous les champs de GodLaws (protocol.py:108) — type, plage et valeur par défaut. Modifiables via POST /api/laws ou par préréglage.

Préréglages — Mondes prêts en un clic

'sustainable' offre une paix durable de 1000 jours. Appliquez via le panneau La Sphère ou POST /api/presets/{name}?reset.

Référence de l'API

Routes en direct issues de app.routes + documentation Swagger à /docs. Essayez les exemples curl ci-dessous.

Exemples de requêtes interactives Curl

# Consultation et réglage des lois divines
curl localhost:8000/api/laws
curl -X POST localhost:8000/api/laws -H 'content-type: application/json' -d '{"food_count": 90}'

# Préréglages en un clic (monde durable de 1000 jours)
curl -X POST localhost:8000/api/presets/sustainable?reset=true
curl -X POST localhost:8000/api/presets/chaos
curl -X POST localhost:8000/api/presets/extinction?reset=true

# État du monde en direct et registre d'histoire
curl localhost:8000/api/state | jq .tick
curl localhost:8000/api/history?limit=5 | jq
curl localhost:8000/api/worlds | jq
curl localhost:8000/api/clans | jq

# Contrôle du temps de la simulation
curl -X POST localhost:8000/api/control -H 'content-type: application/json' -d '{"action":"pause"}'
curl -X POST localhost:8000/api/control -d '{"action":"reset"}'

# Flux WebSocket en direct
# ws://localhost:8000/ws  → Réception de {"type":"hello"} puis du flux {"type":"state"} à ~30Hz
# Envoi de commandes : {"action":"pause"} ou {"action":"set_speed","value":20}