Bách khoa toàn thư & Wiki Flatland

> Trang chủ / Landing Page: /

> Các kho mã nguồn: flws (Backend) · flws-web (Web Frontend) · flws-page (Trang giới thiệu)

> Phát triển bởi Long Phan ([email protected] · Bản demo: /demo/)

> Xây dựng và hoàn thiện bằng OpenCode & Antigravity · Phát triển từ ý niệm nền tảng trong danh tác Flatland: A Romance of Many Dimensions (1884) của Edwin A. Abbott.

Flatland là một thế giới mô phỏng sự sống nhân tạo 2D tự hành, vận dụng sáng tạo các tiền đề toán học và không gian từ tác phẩm kinh điển Flatland (Xứ Phẳng) xuất bản năm 1884 của Edwin A. Abbott.

Triết lý thiết kế

Dự án được phát triển từ ý niệm cốt lõi của Xứ Phẳng chứ không sao chép máy móc từng câu chữ trong tiểu thuyết. Hệ thống tiếp thu các tiên đề hình học của Abbott — mặt phẳng 2D, trật tự xã hội dựa trên số đỉnh, tầm nhìn trong sương mù và góc quan sát từ chiều không gian cao hơn — để kiến tạo một hệ sinh thái sự sống nhân tạo tự sinh, tự thích nghi và phát triển hữu cơ theo thời gian.

Kiến trúc & Các hệ thống cốt lõi

• Khối Cầu (Đấng Sáng Tạo): Khối Cầu (The Sphere) ban hành thiên luật tự nhiên (sức tải môi trường, tốc độ mọc cây, trao đổi chất, dịch bệnh, thời tiết) từ Spaceland, hoàn toàn không can thiệp thô bạo vào số mệnh cá thể. Người dùng có thể điều chỉnh qua 🎯 Thiết lập mẫu và 6 ⚖️ Lĩnh vực Vĩ mô bằng thanh trượt trực quan. Sinh vật định hướng liên tục qua 16 cảm biến tia quét và mạng nơ-ron Micro-RNN.
• Sinh thái thực vật & Dinh dưỡng chức năng: 6 loài thực vật chuyên biệt (cỏ, lúa mì, quả mọng, thảo dược, nấm, cây độc) với mật độ calo riêng biệt, đồng hồ phân hủy, dược tính trị bệnh và hành vi tự tìm kiếm thức ăn theo nhu cầu sinh tồn.
• Trí tuệ nhân tạo & Xã hội thị tộc: AI thỏa dụng đa mục tiêu đánh giá sinh tồn, nghĩa vụ và gắn kết huyết thống; bản đồ tinh thần ghi nhớ địa hình; đội hình phalanx của binh sĩ, chiến thuật thả diều linh hoạt của nữ giới (đoạn thẳng), kết bạn đồng hành dựa trên tin cậy, phân công lao động thị tộc, các thể chế (Quân chủ, Thần quyền, Quân phiệt, Cộng hòa), sắc lệnh thích ứng (phát chẩn mùa đông, thiết quân luật), cớ tuyên chiến (Casus Belli), đoàn buôn liên tộc và đại yến mùa thu mừng vụ mùa.
• Tiến hóa tự hành & Bản sắc văn hóa: 6 hình mẫu tính cách di truyền (dũng cảm, thận trọng, vị tha, tư lợi, khai phá, xây dựng), công cụ chế tác (giáo, túi cói, thuốc đắp, vương miện thủ lĩnh), 4 kỹ năng tinh thông (Nông canh 🌾, Chiến đấu ⚔️, Hái lượm 🦴, Y thuật 🌿), tước hiệu động, truyền dạy tri thức trong nhà ở và hiển thị suy nghĩ trực quan.
• Năng lượng & Trao đổi chất thực tế: Con non tiêu hao ít năng lượng ($0.45\times$), thể lực sụt giảm khi tác chiến, và thói quen dự trữ thức ăn trong túi cói.
• Ấp định cư & Bang giao: Nhà tường kín có cửa ra vào vừa vặn kích thước cơ thể, lãnh thổ thị tộc đa công trình, kho lương chung, khối liên minh phòng thủ, nộp cống và phân liệt ly khai khi bất mãn.
• Vật lý hình học & Đột biến hình thái (K∈[3,24]): Bộ gen cực $(r_i,\phi_i)$ $K\in[3,24]$ (KMAX 24, morphology_engine.py) với đặc tính thể chất tích hợp ($A,P,I_{zz},\theta_{\min},asym,D_{mult}$) và va chạm đa giác SAT; cơ chế ủ nhiệt $\lambda(g)$ dung hòa giữa chuẩn mực Abbott cổ điển và tiến hóa tự do, ghép đôi nơ-ron, cùng mạng lưới bảo hộ chống tuyệt diệt ($\eta(N)$, Phép Miracle Khai Thế Cấp 1/2/3).
• Gương Phản chiếu Bộ gen Tiến hóa : Trực quan hóa kiểu hình sinh động nơi thân thể, vành nhật hoa và ánh sáng phát quang phản chiếu trực tiếp bộ gen sống, độ sâu thế hệ (Gen 0 → 2000+) và đột biến thể chất qua hàng thiên niên kỷ.
• Đồng bộ hóa thời gian thực: Vòng lặp mô phỏng xác định truyền phát trạng thái thế giới qua WebSocket (/ws) ở tốc độ ~30–60 FPS kết hợp lưu trữ biên niên sử bền vững trên SQLite.

Xứ Phẳng: Đối Chiếu Tiểu Thuyết Abbott & Bản Mô Phỏng

Khảo cứu đối chiếu giữa danh tác châm biếm kinh điển năm 1884 của *Edwin A. Abbott — Flatland: A Romance of Many Dimensions*** và hệ sinh thái mô phỏng sự sống nhân tạo tự hành.

---

1. Giai tầng, Hình học & Trật tự Xã hội

| Khía cạnh | Tiểu thuyết của Abbott (Flatland, 1884) | Bản Mô Phỏng (Flatland Simulator) |

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

| Nguyên lý giai tầng | "Hình thù làm nên địa vị." Thứ bậc xã hội được ấn định nghiêm ngặt bởi số lượng cạnh và độ đều của các góc. | Các cá thể kế thừa giai tầng hình học chính xác dựa trên số đỉnh (đa giác N cạnh) và tính đều đặn. |

| Phụ nữ (Đoạn thẳng) | Là các đoạn thẳng không có độ dày góc. Do gần như vô hình khi nhìn trực diện và sắc bén như dao cạo, họ buộc phải liên tục cất tiếng ngâm nga hòa bình và đi lối cửa phụ. | Hiển thị dưới dạng đoạn thẳng 1D (shape: 'line'). Cực kỳ linh hoạt, có tập tính di chuyển và nhu cầu trú ẩn đặc thù. |

| Binh lính & Tiền đạo | Tam giác cân với góc đỉnh rất nhọn hoắt (hung hãn, hiếu chiến, mầm mống bạo loạn). | Binh sĩ (#ff7b72): Chiến binh sắc bén với sát thương cao, kỷ luật tác chiến và tuần tra bảo vệ biên giới. |

| Thợ thủ công & Trung lưu | Tam giác đều (3 cạnh bằng nhau) — tầng lớp lao động và buôn bán ổn định, đáng kính. | Nghệ nhân (3–4 cạnh, #f2cc60): Nông dân, thợ hái lượm và thợ xây phụ trách thu hoạch mùa màng, chăm sóc vựa lương và sửa chữa nhà cửa. |

| Thân sĩ & Quý tộc | Hình vuông (4 cạnh) và Ngũ giác (5 cạnh) — tầng lớp quản lý hành chính và học giả. | Thân sĩ (4 cạnh, #ffa657) & Học giả (5 cạnh, #d2a8ff): Đảm nhiệm vai trò quản lý và điều hành cộng đồng. |

| Giới Quý tộc thượng lưu | Lục giác (6 cạnh) và các đa giác bậc cao — giới quý tộc và nhà lập pháp. | Quý tộc (6–8 cạnh, #79c0ff): Có tiếng nói xã hội lớn và vị thế ưu tiên trong gia phả dòng tộc. |

| Tế tư (Hình tròn) | Đa giác có vô số cạnh (≥ 24 đến hàng trăm) đến mức các đỉnh tạo thành đường tròn trơn láng. Nắm giữ luật pháp và đức tin. | Tế tư (≥ 24 cạnh, #e6edf3): Tỏa ánh hào quang chữa lành vết thương, xua tan mầm bệnh cho đồng tộc và miễn nhiễm dịch tễ. |

---

2. "Định luật Tự nhiên" & Sự Thăng tiến Dòng tộc

• Trong Tiểu thuyết:

- Abbott xây dựng "Định luật Thăng tiến": Con trai của đa giác đều hầu như luôn thừa hưởng nhiều hơn cha mình một cạnh (ví dụ: Hình Vuông sinh ra Ngũ Giác, rồi sinh ra Lục Giác), nâng tầm dòng dõi hướng tới sự hoàn hảo tròn trịa của Tế tư qua nhiều đời.

- Những cá thể "Dị dạng" (các cạnh/góc bất thường) bị coi là mối họa cho xã hội và bị cách ly hoặc xử tử.

• Trong Ứng dụng Mô phỏng:

- Tiến hóa thế hệ: Thế hệ con kế thừa các đặc tính từ cha mẹ với xác suất tăng thêm cạnh (sides += 1), mô phỏng chân thực sự thăng tiến dần dần qua các thời kỳ lịch sử.

- Dị tật & Giáng cấp: Sinh vật phát triển dị tật gen sẽ bị theo dõi độ dị hình, bị giáng cấp và có biểu tượng nhận diện trực quan riêng.

- Gia phả dòng họ: Cây phả hệ lưu giữ chi tiết cha, mẹ và dòng dõi qua hàng trăm ngày lịch sử thế giới.

---

3. Nhận biết Thị giác, Thời tiết & Cảm nhận Sương mù

• Trong Tiểu thuyết:

- Trong thế giới 2 chiều phẳng, mọi cư dân nhìn ngang đều chỉ là những đoạn dẹt!

- Ở Miền Nam Sương mù, cư dân dùng "Nhận biết bằng mắt" — phán đoán góc và khoảng cách của một đa giác qua tốc độ mờ dần của các cạnh trong sương mù.

- Ở Miền Bắc Trong trẻo, họ phải dựa vào "Sờ soạng" (chạm vào các đỉnh bằng đầu ngón tay).

• Trong Ứng dụng Mô phỏng:

- Động cơ thời tiết động: Tái hiện 4 trạng thái Quang đãng, Sương mù, Mưa và Giông bão.

- Tầm nhìn khí quyển: Sương mù và giông bão trực tiếp thu hẹp bán kính quan sát, buộc sinh vật phải dựa vào tiếng hú báo động và cảm biến khoảng cách gần.

- Ngày & Đêm: Cường độ chiếu sáng thay đổi tự nhiên qua bình minh, giữa trưa, hoàng hôn và đêm tối mịt mùng, thúc đẩy sinh vật tìm đường về nhà trú ẩn.

---

4. Nhà ở, Khu định cư & Kiến trúc Lãnh thổ

• Trong Tiểu thuyết:

- Nhà ở bắt buộc phải có hình ngũ giác hoặc lục giác với cửa riêng: cửa nhỏ phía sau cho phụ nữ (đoạn thẳng) và cửa chính cho nam giới đa giác.

• Trong Ứng dụng Mô phỏng:

- Kinh tế định cư: Nhà cửa là cấu trúc vật lý 2D với ranh giới bên trong, cửa ra vào có hướng (bắc, đông, nam, tây) và số chỗ ngủ giới hạn.

- Bản doanh duy nhất: Mỗi thị tộc sở hữu đúng một Nhà Chính / Bản doanh (nơi ở của Thủ lĩnh) cùng các chòi trú ẩn vệ tinh bao quanh.

- Nhu cầu trú ẩn: Sinh vật tìm về nhà để ngủ khi màn đêm buông xuống, tránh rét buốt mùa đông, hồi phục sinh lực và nuôi dưỡng con non.

- Điều hướng qua cửa: Sinh vật tính toán điểm đứng chờ thông minh để di chuyển mượt mà qua khe cửa khi trời tối và tỏa ra tìm thức ăn khi bình minh, không bị kẹt vào vách tường.

---

5. Bang giao Thị tộc, Đồ đằng & Xã hội Tự hành

Khác với mô hình chính quyền tập quyền thời Victoria trong sách, ứng dụng triển khai mô phỏng xã hội tiến hóa tự sinh:

• Đồ đằng Thần thánh: Mỗi thị tộc tôn sùng một trong 8 Đồ đằng thiêng của Khối Cầu (⭕ Sung Túc, ⚡ Nộ Thần, 👁️ Toàn Tri, 🛡️ Trường Tồn, 🌿 Tái Sinh, ⚖️ Cân Bằng, 🌀 Huyền Bí, 🕯️ Bếp Ấm), định hình thiên hướng nghề nghiệp và sự chuyên môn hóa giữa các chiến binh, nông dân và thợ hái lượm.
• Bang giao, Cống nạp & Chiến tranh: Quan hệ thị tộc diễn tiến linh hoạt với hòa ước đình chiến, liên minh tương trợ, cống nạp bảo hộ và nguy cơ phân liệt nội bộ.
• Tính cách độc lập: Các hình mẫu tính cách (Dũng cảm, Thận trọng, Vị tha, Tư lợi, Khai phá, Xây dựng) mang túi cói cá nhân, công cụ (giáo, thuốc đắp, vương miện) và phản xạ tự cứu mình khi nguy cấp.

---

6. Chiều Không Gian Cao Hơn: Người Dùng Trong Vai "Khối Cầu"

Mối liên kết sâu sắc nhất giữa ứng dụng và tiểu thuyết chính là vai trò của người quan sát:

• Trong tiểu thuyết, nhân vật chính A Square (Hình Vuông) được viếng thăm bởi Khối Cầu (A Sphere) đến từ Không Gian 3D (Spaceland), người có thể nhìn từ trục Z xuống, thấy được bên trong các căn phòng kín, nhìn thấu tâm can và thao túng mặt phẳng 2D như một Đấng Sáng Tạo toàn năng.
• Trong Ứng dụng của chúng ta:

- Bạn chính là Khối Cầu (Chúa): Khi nhìn vào màn hình, bạn đang quan sát Xứ Phẳng từ chiều không gian thứ ba.

- Bảng Khối Cầu: Bạn nắm giữ quyền năng tối thượng để ban bố "Thiên luật Tự nhiên" theo thời gian thực — tạo ra nạn đói, điều chỉnh sinh trưởng thức ăn, phát tán hoặc chữa lành dịch bệnh, mang mùa đông buốt giá đến hoặc ban phước lành thịnh vượng cho các thị tộc.

Cấu hình & Vận hành

Biến môi trường (FLATWORLD_*)

| Biến môi trường | Mặc định | Ý nghĩa & Mô tả |

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

| FLATWORLD_WIDTH | 400 | Chiều rộng không gian thế giới (đơn vị lưới) |

| FLATWORLD_HEIGHT | 300 | Chiều cao không gian thế giới |

| FLATWORLD_BOUNDARY | wrap | Biên giới vô hạn hình xuyến (wrap) hoặc tường chặn (clamp) |

| FLATWORLD_SEED | 42 | Hạt giống ngẫu nhiên khởi tạo thế giới |

| FLATWORLD_TICK_RATE | 10 | Số tick tính toán mô phỏng mỗi giây |

| FLATWORLD_DB | backend/flatworld.db | Đường dẫn tệp cơ sở dữ liệu SQLite |

| FLATWORLD_GOD_KEY | — | Khóa mật mã Thượng đế thiết lập lúc khởi động |

Khóa mật mã Thượng đế (God Passkey)

Các thao tác POST /api/laws, POST /api/presets/{name}, POST /api/control và thông điệp điều khiển qua WebSocket yêu cầu quyền Thượng đế (thông qua header X-God-Key hoặc trường key trên socket). Nếu hệ thống chưa có mật mã, API sẽ trả về lỗi 409 Conflict và giao diện web sẽ yêu cầu khởi tạo (POST /api/auth/setup). Nếu quên mật mã, có thể đặt lại trực tiếp trên máy chủ bằng lệnh: cd backend && uv run python -m app.godkey reset <mật_mã_mới>. Giao diện TUI có thể nhận mật mã qua lệnh: ./run.sh tui ws://host/ws <passkey> hoặc biến môi trường FLATWORLD_GOD_KEY. Hệ thống chỉ lưu trữ chuỗi băm bảo mật PBKDF2.

Cơ chế lưu trữ dữ liệu bền vững (db.py:20)

Cơ sở dữ liệu SQLite flatworld.db chạy ở chế độ ghi nhật ký trước WAL (Write-Ahead Logging) và khóa luồng an toàn. Các bảng dữ liệu chính:

• worlds: Thông tin các thế giới (mã số, seed, kích thước, thời điểm bắt đầu/kết thúc).
• events: Biên niên sử biến cố thế giới (sinh, tử, thăng hạng, chiến tranh, dịch bệnh).
• law_changes: Nhật ký thay đổi các định luật của Thượng đế theo tick.
• creatures: Gia phả dòng dõi sinh vật (cha mẹ, thế hệ, thời điểm sinh/tử).
• snapshots: Các bản sao lưu trạng thái thế giới để khôi phục khi khởi động lại.

Kiến trúc luồng & Động cơ SimEngine

Lõi mô phỏng được thiết kế tất định tuyệt đối: một luồng số ngẫu nhiên duy nhất, một thứ tự thực thi tick cố định. Chạy uvicorn với 1 worker duy nhất. Với kiến trúc SimEngine (main.py:446), việc tính toán mô phỏng diễn ra trên một luồng OS nền chuyên trách độc lập với vòng lặp sự kiện asyncio. Bước tiến thế giới diễn ra dưới khóa RT.lock trong khi việc mã hóa JSON snapshot diễn ra bên ngoài khóa (advance_world_lockless), giúp các yêu cầu HTTP REST luôn phản hồi tức thì mà không bị nghẽn. Các điểm cuối vận hành & chẩn đoán quan trọng:

• GET /healthz — Kiểm tra sức khỏe máy chủ, TPS thời gian thực, dung lượng RAM, thời gian chạy và số client kết nối.
• GET /api/perf/telemetry — Vòng đo lường hiệu năng: thời gian tick, thời gian giữ khóa và độ trễ phát sóng.
• GET /api/analytics/summary — Tổng hợp dữ liệu vĩ mô nhân khẩu học, sinh khối và chuỗi thức ăn.

Nguyên lý vận hành thế giới

The Sphere (Thượng đế ba chiều): The Sphere thiết lập các định luật tự nhiên từ Spaceland, tuyệt đối không can thiệp vào số phận của từng sinh vật riêng lẻ. Mọi hành vi và trật tự đều tự vận hành phát sinh.

Vòng lặp tick tất định

s = Simulation(Config(seed)) → s.step() hoàn toàn tất định (mỗi thế giới dùng đúng một luồng số ngẫu nhiên random.Random). Cùng một seed ban đầu sẽ luôn tạo ra cùng một diễn biến lịch sử. Thứ tự thực thi mỗi tick (backend/app/simulation/core.py Simulation.step()): thời tiết → cây cối sinh trưởng → cập nhật lưới không gian → sinh vật hành động → bệnh dịch lây lan → chiến tranh giao tranh → sinh sản → quan hệ ngoại giao → luật cân bằng thức ăn → xác chết phân hủy → khu định cư → tăng tick+=1. Quá trình tính toán chạy trên một luồng hệ điều hành riêng biệt (SimEngine) với cơ chế tuần tự hóa không khóa (lockless), truyền phát trạng thái qua WebSocket state mỗi tick.

Vòng đời & Các giai đoạn (§A)

Tuổi thọ tính theo tick + đẳng cấp (từ Phụ nữ 4.800 tick đến Tu sĩ 9.000 tick). Phân chia giai đoạn theo tỷ lệ tuổi/tuổi thọ: Sơ sinh (<15%), Vị thành niên (<30%), Trưởng thành (<75%), Lão niên (≥75%). Tuổi tác ảnh hưởng đến tốc độ di chuyển và tầm nhìn (sơ sinh 0.6×, lão niên 0.85×) cũng như khả năng sinh sản (lão niên giảm 50%). Nguyên nhân tử vong gồm: starvation (chết đói), old_age (già yếu), euthanasia (thanh lọc dị hình), và disease (bệnh tật).

Cơ chế sinh lực cốt lõi (§AT-4 H-0)

Máu (HP) là một nguồn tài nguyên biến động, không phải hằng số cố định. Để tự hồi phục vết thương, sinh vật bắt buộc phải có năng lượng dồi dào: khi năng lượng dưới 40% energy_max (HEALTH_REGEN_MIN_ENERGY), mọi vết thương sẽ ngừng khép miệng dù đang thức hay ngủ; nghỉ ngơi trong nhà hồi máu theo tỷ lệ 0.15×rest_recovery_mult, còn hồi phục tự nhiên khi thức là 0.1/tick (cộng thêm giáp phòng thủ từ avatar Indomitable Monolith). Khi năng lượng tụt dưới 20%, cơ thể tự thiêu đốt sinh lực: giảm −0.05 HP/tick (HEALTH_SELF_DRAIN_*) dẫn tới chết vì kiệt sức. Sinh lực suy yếu làm chậm từng bước chân (HEALTH_SPEED_TIERS): HP <80 tốc độ ×0.95, <60 ×0.85, <40 ×0.70, <20 ×0.50. Cơ thể đau ốm không thể phối ngẫu: sinh sản yêu cầu health ≥ REPRO_MIN_HEALTH (50 HP), do đó dịch bệnh sẽ ức chế tỷ lệ sinh mà không cần can thiệp vào định luật sinh sản.

Đa dạng sát thương & Kinh tế trị liệu (§AT-4 H-1)

Đói kinh niên tàn phá cơ thể: dưới 20% năng lượng quá 30 tick sẽ rút 0.08 HP/tick (nguyên nhân tử vong exhaustion). Tuổi già bào mòn: sinh vật già mất thụ động 0.02 HP/tick. Bệnh tật làm mờ mắt (HP <60 giảm tầm nhìn 10%, <30 giảm 25%) và làm cùn khả năng thu hoạch (giảm 20% sản lượng khi HP <60, giảm 50% khi <30). Sinh vật bị thương nặng (<30 HP) không bao giờ chủ động gây hấn quyết đấu. Đòn đánh lớn (>15 sát thương) để lại vết thương sâu kéo dài 50–100 tick làm giảm tốc độ và giảm một nửa khả năng hồi máu. Vị trí đứng quyết định tốc độ bình phục: ngoài trời chỉ đạt 50% tốc độ hồi phục so với 80% khi ở trong nhà và 100% khi ngủ say. Thức ăn có tác dụng dược lý: quả mọng hồi +0.3 HP/tick trong 20 tick, ngũ cốc +0.2 HP trong 30 tick, thảo dược +0.8 HP trong 40 tick — sinh vật bị thương sẽ chủ động tìm thảo dược kể cả khi no bụng.

Tiên đề vật lý tự nhiên (§AQ PH-0)

Năng lượng là đơn vị tiền tệ phổ quát của Flatland. Ánh sáng mặt trời là nguồn thu nhập năng lượng duy nhất: hàm _sun_factor() tuân theo chu kỳ ngày đêm — bằng 0 vào ban đêm và đạt đỉnh vào buổi trưa — kiểm soát tốc độ lớn của cây và gieo hạt, nên không loài cây nào có thể lớn tự do trong bóng tối. Mỗi hình dạng cơ thể trả phí tiêu hao theo độ phức tạp hình học (METABOLIC_COST): tam giác 1.0×, tứ giác 1.1×, ngũ giác 1.2×, lục giác/quý tộc 1.3×, phụ nữ và tu sĩ 1.5× (tu sĩ tiêu tốn năng lượng để duy trì hào quang). Chữa lành vết thương là quá trình chuyển hóa: mỗi điểm HP phục hồi tiêu tốn 0.5 điểm năng lượng.

Nhiệt động lực học & Thân nhiệt (§AQ PH-1)

Bản đồ nhiệt độ không gian chia thành các ô 25 đơn vị (_update_temperature) dao động theo mùa (Xuân 12°C / Hạ 24°C / Thu 8°C / Đông −4°C) tạo ra các luồng gió lạnh từ phía Tây và gió ấm từ phía Đông, cộng thêm biên độ ngày đêm (±5°C), thời tiết (mưa −2°C, bão −3°C) và ngọn lửa (+60°C trong bán kính 8 đơn vị). Mỗi sinh vật mang thân nhiệt riêng (body_temp) cân bằng dần theo môi trường. Đứng trong nhà vật liệu rơm, gỗ, đá giúp cách nhiệt về mức dễ chịu 18°C. Quá nhiệt trên 36°C làm mất máu dẫn đến tử vong do say nắng (hyperthermia); lạnh cóng dưới 2°C gây hạ thân nhiệt.

Gió & Khí quyển (§AQ PH-2)

Bầu trời mang một vector gió (wind_angle/wind_speed) thay đổi theo thời tiết: lặng gió 0.25, mưa 0.55, bão tố 1.0 và đổi hướng theo mùa. Ngọn lửa tuân theo chiều gió: cả xác suất bén lửa và tốc độ cháy lan nhân với hướng xuôi gió, khiến đám cháy lan nhanh về phía cuối gió.

Di truyền & Quy luật đẳng cấp (§B)

Giới tính: đa giác là giống đực, đoạn thẳng một chiều là giống cái. Con trai thừa kế số cạnh từ cha: số cạnh = cha + 1, giới hạn tối đa 24 cạnh (Trở thành Tu sĩ hình tròn). Con gái luôn là đoạn thẳng. Đột biến cạnh gây ra độ bất đối xứng (irregularity từ 0.3 đến 1.0). Tam giác cân có góc đỉnh tăng dần 0.5° mỗi thế hệ; khi đạt ≥60° trở thành tam giác đều và thăng hạng từ Binh lính lên Thợ thủ công. Động cơ hình thái (morphology_engine) dùng hệ tọa độ cực $(r_i,\phi_i)$ để nội suy hình thái chuyển tiếp qua các thế hệ.

Động cơ hình thái & Hình học cực (K∈[3,24])

Bộ gen cực $K\in[3,24]$ lưu trữ cấu trúc SoA gồm bán kính, góc, diện tích, chu vi, mômen quán tính $I_{zz}$, góc nhỏ nhất $\theta_{\min}$ và hệ số bất đối xứng $asym$. Tự động điều chỉnh dung lượng năng lượng, lực đẩy và tính sát thương va chạm. Có cơ chế cứu rỗi (safeguard_morph_mercy) tạm hoãn thanh lọc dị hình khi dân số suy kiệt.

Biên niên sử, Lịch sử Thế giới & AI Kể chuyện (§BM)

Flatland trang bị hệ thống phân tích biên niên sử đa thời kỳ và trợ lý viết truyện AI toàn diện:

• Khoảnh khắc Then chốt & Nhảy mốc thời gian: 5 ngày biến động lớn nhất (thương vong, thôn tính, ly khai) hiển thị dạng chip nhảy nhanh trên bảng biên niên. Cho phép gõ số tick để nhảy tức thì đến thời khắc lịch sử.
• Thanh Kỷ nguyên & Đồ thị Dân số: Điều hướng dòng thời gian với các kỷ nguyên màu sắc (Khởi nguyên, Thời bộ lạc, Kỷ phong kiến, Cực thịnh, Suy vong) cùng biểu đồ dân số đánh dấu khủng hoảng chiến tranh và dịch bệnh.
• Bảng Kỷ lục & Huyền thoại: Vinh danh Bộ tộc hiếu chiến nhất, Ngày đẫm máu nhất, Đế chế đông dân nhất, Kiến trúc sư Thần thánh dựng nhiều đền nhất, Đại biến ly khai và các cá thể Anh hùng / Kẻ phản nghịch tiêu biểu.
• Phân tích Lịch sử: Ma trận Nhiệt Thù địch giữa các bộ tộc, Biểu đồ Nguyên nhân Tử vong theo kỷ nguyên 10 ngày và Chỉ số Đức tin theo dòng thời gian.
• Trình Viết truyện AI Tích hợp: Trực tiếp tạo truyện dạng tiểu thuyết hoặc biên niên sử bằng Gemini 1.5 Flash hoặc OpenAI GPT-4o-mini với khóa API lưu riêng tại trình duyệt người dùng. Hỗ trợ 4 phong cách văn phong (Sử thi, Biên niên, Thần thoại, Bi kịch) bằng cả 3 ngôn ngữ EN, VI, FR.
• Liên kết Sâu & Thẻ Chia sẻ: Hỗ trợ đường dẫn ?history=42 để mở trực tiếp ngày thứ 42 hoặc ?clan=7 để mở tiểu sử bộ tộc #7, cùng nút tải ảnh thẻ xã hội chuẩn 1200×630 PNG.

Phân cấp đẳng cấp & Dị hình (§C)

Đến tuổi trưởng thành, nếu mức độ bất đối xứng vượt ngưỡng (euthanasia_threshold), sinh vật sẽ bị xã hội đào thải tiêu hủy; nếu nhẹ hơn sẽ bị giáng cấp làm Binh lính thường. Bảng CASTE_TRAITS quy định tuổi thọ, tốc độ, tầm nhìn và độ màu mỡ của từng đẳng cấp.

Dịch bệnh & Lây nhiễm (§D)

Dịch bệnh tự phát theo tỷ lệ quy định, lây lan trong bán kính tiếp xúc (mùa đông lây nhanh hơn 1.5×), rút cạn năng lượng và trừ máu theo độc lực bệnh. Sinh vật có thể dần bình phục nhờ sức đề kháng tự nhiên hoặc ăn thảo dược.

Môi trường & Khí hậu (§E)

Thời gian tính theo chu kỳ ngày đêm và 4 mùa trong năm. Ban đêm và sương mù làm giảm tầm nhìn đáng kể. Mùa màng ảnh hưởng trực tiếp đến hệ số thức ăn: Mùa xuân (1.0× thức ăn, +25% sinh sản), Mùa hè (1.2×), Mùa thu (1.0×), Mùa đông (0.5× thức ăn, +50% nguy cơ dịch bệnh). Thời tiết thay đổi ngẫu nhiên giữa Trời quang, Mưa rào, Sương mù và Bão tố.

Bộ tộc & Trật tự xã hội (§C/I/P/V)

Mỗi ngôi nhà vững chắc khởi nguồn cho một bộ tộc do sinh vật gần tâm nhà nhất làm thủ lĩnh. Con cái mang mã bộ tộc của mẹ. Bộ tộc tôn thờ một trong 8 Linh vật Thần thánh (Vòng tròn Rạng rỡ, Sấm sét Thiên giới, Con mắt Thấu thị, Cự thạch Kiên cường, Vòng xoắn Thần thánh, Bàn cân Vũ trụ, Vết rách Chiều không gian, Ngọn lửa Vĩnh cửu) mang lại bùa chú riêng. Các tộc nhân đóng góp đức tin để thỉnh cầu phép màu mùa màng hoặc xây dựng Đền thờ thiêng liêng.

Kinh tế thực phẩm & Hệ sinh thái (§H/N/O)

Cây cối phát triển từ mầm non đến trưởng thành và phát tán hạt giống trong bán kính xung quanh. Sinh vật chết để lại xác thịt có thể ăn được hoặc phân hủy nuôi dưỡng đất đai. Hệ thực vật đa dạng gồm 6 loài: Cỏ thông thường, Hạt ngũ cốc, Quả mọng tăng tốc, Thảo dược hồi máu, Nấm hoại sinh và Cây có độc. Thú ăn cỏ hoang dã tự do sinh sôi và là mục tiêu săn mồi của các loài ăn thịt.

Giao tiếp & Tri thức bầy đàn (§Q/X)

Sinh vật phát tín hiệu gọi ăn hoặc cảnh báo nguy hiểm cho đồng loại. Kinh nghiệm sống (điểm kiếm ăn, mối nguy hiểm, nơi an toàn, kẻ thù) được lưu giữ trong trí nhớ và truyền dạy cho nhau khi trò chuyện. Khi một cá thể bị tấn công, tiếng kêu cứu sẽ triệu tập các chiến binh gần đó đến ứng cứu.

Chính trị & Bang giao (§AB)

Các bộ tộc thân thiện có thể ký hiệp ước liên minh phòng thủ chung, chia sẻ kho lương thực, hoặc thu cống nạp từ các tộc yếu thế hơn. Thủ lĩnh dũng cảm sẽ tuyên chiến với kẻ thù truyền kiếp, trong khi thủ lĩnh ôn hòa sẽ tìm kiếm hiệp ước hòa bình khi thế lực suy giảm.

Ăn thịt đồng loại khi tuyệt vọng (§AC)

Khi nạn đói đỉnh điểm khiến năng lượng chạm đáy tuyệt vọng, sinh vật bị ép phải tấn công và ăn thịt các sinh vật yếu thế hoặc kẻ thù để sinh tồn. Kẻ ăn thịt đồng tộc sẽ bị xã hội ruồng bỏ, trở thành kẻ lưu đày và tạo nên mối thù truyền kiếp.

Cây héo tàn & Tự nhiên luân hồi (§AE)

Cây cối trưởng thành sau một khoảng thời gian sẽ già cỗi và héo úa, giải phóng chất dinh dưỡng cho đất đai xung quanh trước khi biến mất, nhường chỗ cho các mầm sống mới nảy nở.

Nhà ở & Nơi trú ẩn định cư (§L/N)

Nhà cửa bằng gỗ, rơm hoặc đá che chắn mưa bão và cái lạnh ban đêm. Cửa nhà được thiết kế vừa vặn cho cư dân nhưng quá hẹp đối với các dã thú ăn thịt hung dữ, tạo thành nơi trú ẩn an toàn tuyệt đối.

Tiến hóa tự chủ & Công cụ (§AG)

Sinh vật sở hữu các thiên hướng tính cách bẩm sinh (dũng cảm, thận trọng, vị tha, tham lam, thám hiểm, xây dựng). Tự động chế tạo và mang theo công cụ: Giáo chiến đấu, Giỏ đựng thức ăn, Túi thảo dược và Vương miện thủ lĩnh. Rèn luyện 4 kỹ năng chính: Canh tác, Chiến đấu, Kiếm ăn và Trị liệu.

Trao đổi chất & Thể lực chiến đấu (§AH)

Nhu cầu năng lượng thay đổi theo giai đoạn phát triển: trẻ nhỏ tiêu thụ ít hơn 55%, thiếu niên ít hơn 25%. Va chạm chiến trận làm tiêu hao thể lực; kiệt sức sẽ khiến đòn đánh giảm 30% hiệu lực sát thương.

Trí tuệ bầy đàn Utility AI (§AL)

Hệ thống trí tuệ nhân tạo đa mục tiêu tính toán điểm số sinh tồn, nghĩa vụ đẳng cấp và tín hiệu đồng loại. Sinh vật lập bản đồ tư duy với các tọa độ nhà, vùng thức ăn và điểm tuần tra; phối hợp tác chiến theo đội hình chiến thuật kỷ luật.

Đa dạng sinh học & Dược tính (§AM)

Hạt vàng cung cấp nguồn năng lượng no lâu; Quả mọng ban tặng sự dẻo dai bứt tốc; Thảo dược giải độc và làm lành vết thương; Nấm phân hủy phát triển tươi tốt quanh xác chết và mùa đông giá rét.

Giao diện dòng lệnh TUI (§AI)

Bộ điều khiển giao diện terminal đầy đủ gắn trực tiếp vào thế giới đang chạy, hỗ trợ bám sát góc nhìn sinh vật, lọc biên niên sử sự kiện và điều chỉnh luật chơi trực tiếp.

Mạng nơ-ron hồi quy Elman & Động cơ tiến hóa (BA)

Mỗi sinh vật mang một mạng nơ-ron Elman RNN thu nhỏ (16 đầu vào cảm biến → 12 nơ-ron ẩn → 7 đầu ra vận động với 295 trọng số float32). Vận hành song song ở tần số 15 Hz, tiếp nhận thông tin thị giác raycast, âm thanh, mùi hương và trạng thái nội tại để tự học cách sinh tồn và truyền lại bộ gen ưu việt cho đời sau.

Tính bền vững — Cân bằng sinh thái Đa thế hệ

Thế giới tự động duy trì sự cân bằng qua hàng trăm ngày và tạo điều kiện cho các thị tộc hưng thịnh truyền đời dưới trạng thái cân bằng sinh thái và xã hội hoàn chỉnh.

Các thiết lập mẫu tuyển chọn (Presets)

• balance ⚖️ (Mặc định) — Trạng thái cân bằng vàng cho 200–350 cư dân với 380 thức ăn, sức tải 400 (tối đa 500), chiến tranh vừa độ, chuỗi săn mồi cân bằng, nông nghiệp bài bản, tự hãm mật độ ($\xi$), cơ chế bảo hộ tuyệt chủng ($\eta$) và các thị tộc đa thế hệ phát triển phồn vinh.
• sustainable 🌿 — Nghìn ngày thái bình: thức ăn dồi dào (550), sức tải 550 (tối đa 600), vựa thóc trù phú, lễ hội mùa gặt, đại yến và hãm mật độ êm dịu.
• theocracy 🔮 — Thời đại Khối Cầu: tôn sùng các Đồ đằng thiêng liêng, đại đền rực sáng, thần tích hiển linh, đốn ngộ 3 chiều, công đồng tôn giáo và dâng nộp đức tin.
• warlords ⚔️ — Quần hùng tranh bá: chinh phạt đế chế, cướp bóc kho lương, chiếm đoạt nhà cửa, thôn tính lãnh thổ và thiết lập khối liên minh phòng thủ.
• chaos 🔥 — Thú săn hung dữ bủa vây, huyết chiến đẫm máu, cháy rừng, động đất, dịch bệnh liên miên và thời tiết biến đổi khôn lường.
• extinction 💀 — Nạn đói cùng cực (120 thức ăn), mùa đông giá buốt (0.30×), phơi sương gió kiệt quệ, thử thách sức chống chịu của xã hội trước bờ vực diệt vong.
• boom 🚀 — Đại thịnh vượng: sinh sản bùng nổ, 440 thức ăn, sức tải 800 (tối đa 850) phục vụ thử nghiệm các siêu đô thị sầm uất.

Sử dụng: curl -X POST localhost:8000/api/presets/balance?reset=true hoặc chọn trực tiếp trên Bảng Khối Cầu.

Cân bằng nội môi động & Cơ chế phòng chống diệt vong

Flatland tích hợp hai cơ chế phản hồi khép kín tự động nhằm đảm bảo trật tự dài hạn:

1. Cơ chế hãm mềm phụ thuộc mật độ quá tải ($\xi$)

Khi dân số $N$ vượt quá sức tải môi trường $K_{cap}$, tỷ lệ vượt ngưỡng $\xi = (N - K_{cap}) / K_{cap}$ đóng vai trò như chiếc phanh phi tuyến tính:

• Kìm hãm sinh sản: $R_{birth} = R_0 / (1 + \text{damping\_steepness} \cdot \xi^2)$
• Áp lực trao đổi chất do chật chội: $M_{decay} = M_0 \cdot (1 + \text{crowding\_stress\_mult} \cdot \xi)$
• Căng thẳng tài nguyên: Tốc độ sinh trưởng và phát tán hạt giống chậm lại tương ứng với mức độ bão hòa sinh thái.

2. Cơ chế cứu trợ diệt vong & Phép Màu Khai Thế ($\eta$)

Khi dân số sụt giảm xuống dưới ngưỡng an toàn $K_{safe} = K_{cap} \times \text{safeguard\_relief\_ratio}$, các cấp độ cứu trợ khẩn cấp sẽ kích hoạt:

• Cấp 1 ($\eta \le 0.5$): Cứu tế nạn đói, giảm mức tiêu hao năng lượng trao đổi chất tới 40%, đẩy nhanh cây lớn lên tới 60%.
• Cấp 2 ($\eta > 0.5$): Cứu trợ nguy cấp, giảm một nửa thời gian chờ sinh sản, đình chỉ việc an tử cá thể dị tật (safeguard_morph_mercy).
• Cấp 3 ($N \le K_{crit}$): Khối Cầu can thiệp bằng Phép Màu Khai Thế (Genesis Miracle), tạo ra safeguard_genesis_batch sinh vật hình học hoàn hảo để cứu vãn sự diệt vong của thế giới.

Hiệu năng & Quy mô — Hơn 1000 thực thể @ 60 FPS

• Bảng băm không gian Zero-Allocation: Mảng 1 chiều cấp phát sẵn trong world.py loại bỏ việc tạo bộ tuple và băm lại từ điển mỗi nhịp; hàm query_radius sử dụng so sánh khoảng cách bình phương thoát sớm không cần gọi math.hypot.
• Tìm bạn tình siêu tốc: Truy vấn đối tác tiềm năng lân cận qua chỉ mục không gian trong thời gian $O(1)$ thay vì quét lặp lồng nhau $O(N^2)$.
• Bộ nhớ đệm ảnh chụp (Snapshot Caching): Địa hình tĩnh và công trình được nạp sẵn vào bộ nhớ đệm, loại bỏ việc sao chép danh sách cấu trúc thừa thãi trong mỗi khung hình truyền phát.
• Vẽ gộp nhóm Canvas 2D (Batched Canvas 2D): Gom nhóm các lượt vẽ theo giai tầng, biến thể cây và nhà ở với phép biến đổi lượng giác nội dòng, loại bỏ hoàn toàn chi phí ctx.save() / ctx.restore() cho từng cá thể (lệnh vẽ giảm từ hơn 20.000 xuống còn ~30-50).
• Mức độ chi tiết động (Dynamic LOD): Hiển thị phụ thuộc tỷ lệ thu phóng, tự động lược bỏ văn bản danh tính và gợn sóng khi nhìn xa, bảo toàn độ mượt mà 60 FPS ngay cả khi dân số dày đặc.
• Tách biệt trạng thái React: Ảnh chụp trạng thái mô phỏng tần số cao truyền thẳng vào tham chiếu biến đổi (mutable refs) ở tốc độ 60 FPS cho Canvas, trong khi giao diện React (thống kê HUD, đồ thị) được điều tiết ở tần số ~6 Hz giúp trình duyệt nhẹ nhàng và phản hồi tức thì.

Bản đồ mã nguồn

Kiến trúc 3 Kho mã nguồn & Triển khai hệ thống (§BP)

Flatland được phân rã thành 3 kho mã nguồn GitHub chuyên biệt với phương thức triển khai đồng nhất trên cùng một hệ thống:

• flws (github.com/longphanmn/flws): Động cơ mô phỏng backend thuần túy (FastAPI, luồng SimEngine, SoA NumPy, micro-RNN Elman, SAT hình thái cực, TUI, SQLite WAL). Lắng nghe trên cổng :8000.
• flws-web (github.com/longphanmn/flws-web): Khách web frontend độc lập (React 18, Vite, TypeScript, khung nhìn Canvas2D/WebGL 60 FPS, Đài thiên văn vĩ mô). Triển khai trên GitHub Pages (https://longphanmn.github.io/flws-web/) và chạy trên cổng :5173 / :80 (Nginx reverse-proxy sang backend).
• flws-page (github.com/longphanmn/flws-page): Trang đích giới thiệu chính thức (canvas sinh vật tương tác, huy hiệu âm thanh, cốt truyện). Triển khai trên GitHub Pages độc lập (https://longphanmn.github.io/flws-page/).
• Triển khai đồng nhất cùng hệ thống: docker-compose.yml và deploy.sh tự động triển khai và vận hành cả backend lẫn frontend trên cùng một máy chủ mục tiêu.

Cấu trúc Backend (backend/app/)

• config.py:13 — Dataclass Config: Hình học thế giới, mật độ sinh vật, thức ăn, xác chết, hành vi bầy đàn, sinh sản, dịch bệnh, môi trường, nhà ở, địa hình, xã hội và biên niên sử. Tự động đọc cấu hình từ biến môi trường qua from_env().
• entities.py:1 — Định nghĩa các thực thể cốt lõi: CasteTraits, CASTE_TRAITS, YIELD_RANK, caste_name(), Creature (hình dạng, số cạnh, đẳng cấp, tuổi tác, máu, trạng thái nhiễm bệnh, bang phái, ngủ...), Food (độ chín sinh trưởng), Corpse (xác chết phân hủy), House (nhà ở, cửa ra vào, quyền sở hữu).
• world.py:32 — Lớp đăng ký thực thể World tích hợp lưới băm không gian đồng nhất (cell_size, rebuild_index), tính toán khoảng cách bao quanh hình xuyến và truy vấn bán kính query_radius.
• simulation/ — Gói động cơ mô phỏng mô-đun hóa (§BI):

- core.py — Lớp điều phối Simulation, vòng lặp tick tất định, đồng bộ khe SoA và làm mới bộ nhớ đệm.

- creature_update.py — Vòng lặp hành vi sinh vật 7 giai đoạn phân rã (_creature_movement, _creature_feeding, v.v.).

- settlement.py — Kinh tế nhà ở, xây dựng, tuyên bố chủ quyền, chiếm nhà và va chạm tường.

- lifecycle.py — Khởi tạo dân số, sinh sản, sinh tử, danh hiệu kỹ năng và lây lan dịch bệnh.

- ecology.py — Vòng đời thực vật, nông nghiệp, yến tiệc, phân hủy xác chết và tái tạo dinh dưỡng.

- theology.py — Quỹ đức tin, 8 Avatar Linh thiêng, đền thờ, phép màu, công đồng và hiển linh.

- society.py — Bang tộc, ngoại giao, chiến tranh, liên minh, kho lương, đoàn buôn và ăn thịt đồng loại.

- serialization.py — Đóng gói dữ liệu snapshot và delta truyền qua mạng.

- environment.py — Máy trạng thái thời tiết, gió, lưới nhiệt độ, độ cao và cháy rừng.

- constants.py — Hằng số bảng tra cứu, hệ số nhân và quy tắc đặt tên.

• agent_soa.py — Mảng cấu trúc SoA vector hóa tối ưu bộ nhớ đệm CPU cho hàng ngàn sinh vật.
• agent_pipeline.py — Xử lý cảm biến raycast và vật lý chuyển động vector hóa hàng loạt.
• neural_engine.py — Mạng nơ-ron hồi quy Elman RNN (16→12→7, 295 trọng số) suy luận trực tiếp.
• morphology_engine.py — Động cơ hình thái cực, va chạm SAT đa giác và thuộc tính thể chất.
• evolution_manager.py — Quản lý ủ nhiệt hình thái λ(g), khuôn mẫu Abbott K3..64 và lai ghép cực.
• spatial_grid.py — Lưới không gian vector hóa phục vụ truy vấn lân cận nhanh chóng.
• analytics.py — Vòng telemetry, chỉ số vĩ mô, nhân khẩu học và đa dạng sinh học.
• safeguard_engine.py — Cơ chế bảo vệ khỏi tuyệt chủng và Phép màu Khởi nguyên.
• density_damping.py — Hãm mềm phụ thuộc mật độ (ξ).
• auth.py:1 — Cơ chế xác thực FastAPI dependency bảo vệ quyền Thượng đế thông qua chuỗi băm PBKDF2 (X-God-Key).
• protocol.py:7 — Định nghĩa lược đồ dữ liệu mạng Pydantic: ControlAction, ControlMessage, EntityState, StateMessage, HistoryEvent, HelloMessage, GodLaws.
• db.py:1 — Lớp bọc SQLite3 Database tối ưu với nhật ký WAL, khóa luồng và bộ đệm ghi nền cho các sự kiện sinh, tử, chiến tranh và snapshot.
• main.py:1 — Điểm khởi đầu FastAPI app, luồng động cơ riêng SimEngine, bộ phát sóng WebSocket Hub, các tuyến API REST và tài liệu /wiki.

Cấu trúc Frontend (frontend/src/)

• App.tsx — Bố cục ứng dụng chính, thanh HUD thông số, đồng bộ WebSocket và bảng điều khiển đa năng.
• analytics/ — Đài thiên văn & Động cơ phân tích vĩ mô (Observatory):

- Observatory.tsx — Khung hiển thị toàn màn hình các bảng phân tích vĩ mô theo thẻ.

- MacroOverview.tsx — Biểu đồ sparkline nhân khẩu học, sinh lực, sinh khối và tốc độ.

- SociologyTab.tsx — Bá quyền bang tộc, đoàn buôn liên bộ tộc, chiến tranh và kế vị.

- EcologyTab.tsx — Đa dạng thực vật, độ màu mỡ đất và tháp sinh thái.

- CrisisTab.tsx — Lây lan dịch bệnh, cảnh báo nạn đói và nhật ký thiên tai.

- MutationLab.tsx — Cây phát sinh hình thái học và biểu đồ phân tán không gian hình thái 2D.

- MetricCard.tsx / Sparkline.tsx — Khung hiển thị thẻ chỉ số và biểu đồ đường nhẹ SVG.

• render/CanvasRenderer.tsx — Bộ hiển thị HTML5 Canvas đồ họa 60 FPS hiệu năng cao với vẽ hàng loạt (batching).
• render/ClanPanel.tsx — Bảng hiển thị thông tin bang phái trực tiếp, cây totem linh vật và chiến tích lịch sử.
• render/ChronicleFeed.tsx — Dòng sự kiện biên niên sử thời gian thực có bộ lọc thông minh.
• render/PlotsPanel.tsx — Biểu đồ sparkline theo dõi dân số, tỷ lệ đẳng cấp và chuỗi thức ăn sinh thái.
• clan/ClanDetails.tsx — Hồ sơ chi tiết bang tộc, nơi cư ngụ của thủ lĩnh và thống kê thương vong.
• history/WorldHistoryModal.tsx — Nhật ký tóm tắt từng ngày, các cuộc đại chiến và tính năng xuất truyện AI Story.
• god/GodPanel.tsx — Bảng điều khiển định luật tự nhiên tương tác với 7 cấu hình mẫu tuyển chọn.
• god/auth.tsx — Hộp thoại xác thực mật mã Thượng đế và hàm gọi API bảo mật godFetch.
• inspect/Inspector.tsx — Bảng hồ sơ cá nhân sinh vật, radar hình thái cực, chỉ số sinh tồn và cây gia phả.
• wiki/Wiki.tsx — Bách khoa toàn thư tích hợp sẵn trong ứng dụng và công cụ thử nghiệm API.
• types.ts — Định nghĩa kiểu TypeScript ánh xạ chính xác lược đồ giao thức backend.
• websocket.ts — Trình khách WebSocket tự động kết nối lại khi gián đoạn mạng.

Luồng dữ liệu hệ thống

SimEngine (luồng riêng) → sim.step() → sim.snapshot() (tuần tự hóa không khóa) → HUB.broadcast → ws → CanvasRenderer + Trạng thái React App. Phía người dùng gửi ControlMessage → apply_control → Cập nhật cấu hình mô phỏng → Lưu nhật ký luật vào DB. Biến cố thế giới → DB.add_events + Lưu hồ sơ gia phả.

Mô hình dữ liệu & Giao thức mạng

Các thực thể trong bộ nhớ (In-memory Entities)

• Creature (entities.py:95): id, tọa độ x, y, góc quay angle, hình dáng shape (đa giác polygon hoặc đoạn thẳng line), số cạnh sides, đẳng cấp caste, bán kính radius, số tuổi age, tuổi thọ lifespan, giai đoạn stage (sơ sinh infant, thiếu niên juvenile, trưởng thành adult, lão niên elder), độ bất đối xứng irregularity, sinh lực health (0–100), nhiễm bệnh infected, giới tính sex, mother_id/father_id, mã bang tộc clan_id/màu cờ clan_color, đang ngủ sleeping/trong nhà indoors, thế hệ generation, thời điểm sinh born_tick, năng lượng energy, trạng thái đói status, số bữa ăn meals.
• Food (entities.py:158): Vị trí x, y, độ chín sinh trưởng growth từ 0.15 đến 1.0.
• Corpse (entities.py:170): Vị trí x, y, thời gian phân hủy còn lại ttl, lượng năng lượng cung cấp energy.
• House (entities.py:184): Vị trí x, y, kích thước nhà size, độ rộng cửa door_width, cạnh đặt cửa door_side, bang tộc sở hữu clan_id/clan_color, dấu hiệu phế tích is_ruin, số tick bị bỏ hoang abandoned_ticks, thời điểm bị chiếm đoạt takeover_tick.
• Địa hình bản đồ (Terrain): Các khu đất màu mỡ fertile: [{x,y,r}] và các mỏ đá cản trở rocks: [{x,y,r}] được đóng gói trong snapshot.

Cấu trúc dữ liệu mạng truyền tải (protocol.py)

• EntityState (protocol.py:27): id, loại thực thể kind (creature | food | house | corpse), tọa độ x/y, hướng quay angle, kèm các trường trạng thái sinh học bổ trợ.
• StateMessage (protocol.py:62): Thông điệp trạng thái toàn thế giới gửi mỗi tick gồm: số tick tick, hạt giống seed, kích thước bản đồ width/height/boundary, tổng dân số population, danh sách thực thể entities, thông tin bang phái clans, số sinh vật sống/chết và nguyên nhân tử vong, số ca nhiễm bệnh, thời điểm trong ngày/ngày/mùa/thời tiết, địa hình, ma trận quan hệ ngoại giao, danh sách biến cố mới phát sinh, kèm khung dữ liệu analytics định kỳ 1 Hz phục vụ Đài thiên văn.
• HistoryEvent (protocol.py:86): Bản ghi sự kiện lịch sử gồm: loại sự kiện type (tử vong, sinh nở, thăng hạng, giáng cấp, bùng dịch, bình phục, cây nở hoa, liên minh, thù địch, săn mồi, tuyên chiến, phế tích, lập ấp), số tick xảy ra, mã thực thể liên quan, đẳng cấp, nguyên nhân, tọa độ và gói dữ liệu bổ trợ payload.
• HelloMessage (protocol.py:99): Thông điệp chào ban đầu khi kết nối WebSocket thành công: hạt giống seed, tốc độ tick tick_rate, giới hạn thế giới width/height/boundary.
• ControlMessage (protocol.py:22): Lệnh điều khiển gửi từ giao diện web lên máy chủ: hành động action (pause tạm dừng, resume tiếp tục, step chạy một bước, reset làm mới thế giới, set_speed chỉnh tốc độ) kèm giá trị số value.

Giao thức đồng bộ WebSocket

Máy chủ gửi về trình duyệt: Gửi {"type":"hello", ...} ngay khi kết nối, sau đó liên tục phát sóng {"type":"state", ...} theo tần số tick (kèm gói analytics 1 Hz cho Đài thiên văn). Trình duyệt gửi lên máy chủ: Gửi gói tin điều khiển {"action":"pause"|"resume"|"step"|"reset"|"set_speed", "value":...}.

Thiên luật của Khối Cầu (The Sphere)

Toàn bộ định luật trong GodLaws (protocol.py:108) kèm kiểu dữ liệu, phạm vi và giá trị mặc định. Thay đổi qua POST /api/laws hoặc chọn thiết lập mẫu.

Thiết lập mẫu — Định hình thế giới với 1 chạm

'sustainable' mang lại nền thái bình thịnh trị 1000 ngày. Áp dụng qua bảng Khối Cầu hoặc lệnh POST /api/presets/{name}?reset.

Tham chiếu API

Danh sách endpoint từ app.routes + tài liệu tương tác tại /docs. Xem các ví dụ curl bên dưới.

Công cụ dòng lệnh Curl thử nghiệm

# Truy vấn và thiết lập định luật tự nhiên
curl localhost:8000/api/laws
curl -X POST localhost:8000/api/laws -H 'content-type: application/json' -d '{"food_count": 90}'

# Áp dụng cấu hình mẫu thế giới 1-chạm (thế giới bền vững 1000 ngày)
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

# Truy vấn trạng thái thế giới và lịch sử biên niên sử
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

# Điều khiển mô phỏng thời gian thực
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"}'

# Kết nối trực tiếp WebSocket
# ws://localhost:8000/ws  → Nhận gói {"type":"hello"} sau đó liên tục nhận {"type":"state"} ~30Hz
# Gửi lệnh điều khiển: {"action":"pause"} hoặc {"action":"set_speed","value":20}