Skip to main content

​
🚀 ARCLUX — Repository War Universe

Repository adalah sumber kebenaran. ARCLUX adalah universe yang
memvisualisasikan, mensimulasikan, dan memberi kehidupan pada repository.
Blueprint strategis — dibaca dengan izin · Lihat docs/blueprint/BLUEPRINT_LICENSE.md sebelum menggunakan. Draf iterasi 1.

​
0. Kompas Strategis

Satu kalimat visi:
ARCLUX menjadi universe tanpa batas tempat setiap software repository menjadi source of truth bagi entitas virtual (kapal) yang dapat divisualisasikan, dikembangkan, ditransfer, dirusak, diperbaiki, dan berjejak sejarah — dengan engine code-intelligence sebagai mesin di baliknya, dan ARCLUX sebagai canvas, bukan konten.
3 prinsip non-negotiable:
  1. Repo user = source of truth. Kapal dibangun user di repo mereka (.arclux/), BUKAN di repo ARCLUX.
  2. ARCLUX = canvas + mesin. ARCLUX membangun universe/aturan/engine; konten (kapal, senjata, system) 100% karya user.
  3. Serangan tidak merusak code asli. Damage hanya menyentuh layer .arclux/ / world-state; repo project aman. “Repair = commit” (bukan tombol).
  4. Combat: visual boleh cinematic, hasil harus deterministic + tervalidasi. Client boleh menggambar perang; client tidak boleh menentukan kebenarannya. “Users create the machines. ARCLUX defines the physics. The server verifies reality.”
Struktur 3 lapis:

​
📚 Indeks Blueprint

Blueprint penuh dipecah ke docs/blueprint/ (multi-file, biar navigable seiring visi yang kian besar). Urutan baca yang disarankan:

​
1. Keputusan Arsitektur

Rekomendasi yang perlu dikunci sebelum eksekusi:

​
2. Arsitektur Teknis

Ringkasan lapisan. Detail desain UX (spatial/stasiun) ada di spec terpisah.

​
Layer A — .arclux/ manifest (objek K1, K3)

Titik baru pertama: file konfigurasi ARCLUX di dalam repo user (belum ada; gap teridentifikasi dari riset).
  • Definisi kapal memakai DSL ARCLUX (packages/dsl) yang sudah live di npm — user memakai bahasa yang ada, bukan bahasa baru.
  • .arclux/state/ = world-state yang di-generate ARCLUX, tetap versioned di repo user → terbawa history → nyambung ke provenance.

​
Layer B — World Model (abstraksi baru; objek K1, K3)

Package baru (mis. packages/universe/):
Mapping stat kapal dari analisis: Ini mewujudkan “makin project berharga → makin kuat”, tapi terukur & anti-abuse (K1-C).

​
Layer C — Component System (objek K3)

  • Component = capability nyata dari SDK/MCP, bukan sekadar skin.
  • Setiap component: id, capability (referensi fungsi SDK), license, provenance, owner.
  • Contoh binding:
    • security-scanner → analyzeRepositorySecurity
    • impact-solver → calculateAffectedFiles
    • route-mapper → mapAttackSurface
    • call-graph → buildCallGraph
  • License 3-tier (LicenseValidator):
    • 🟢 Open — boleh reuse sesuai terms
    • 🟡 Shared — butuh attribution/permission
    • 🔴 Private — hanya owner & yang diizinkan; unauthorized → capability disabled (bukan code rusak)

​
Layer D — Ingestion & Auto-Update (objek K2)

  • Connect: arclux connect <repo-url> (npm/CLI/MCP/SDK yang sudah live) → membuat boilerplate .arclux/.
  • Auto-update: daemon (packages/daemon/) + watcher (packages/watcher/) → event analysis:updated → update VesselModel → push ke web.
    • Gap: web belum consume SSE daemon (/events). Perlu bridge route Next.js (/api/universe/events) + EventSource client.
    • Gap jangka panjang: watchRepository masih full-rebuild; true per-file incremental (packages/incremental) belum di-wire ke buildIndex.

​
Layer E — 3D World (objek K2, K4)

  • Render hub/dashboard memakai three yang sudah ada.
  • 3D kapal: extend pola GraphCanvas3D + GraphAuditOverlay (terbukti bisa drive scene dari luar via fgRef).
  • Mapping: sistem kapal → mesh 3D, health → warna/scale/partikel damage.
  • Kualitas adaptif (resolution/FPS/effects/render distance) — render di client, sim tetap di world-state (FPS tidak menentukan kebenaran sim).
  • Spatial & navigation UX penuh (zoom ladder, camera modes, semantic navigation, adaptive HUD, LOD, combat camera) — lihat docs/blueprint/01-spatial-ux.md.

​
Layer F — Developer World → Debug

  • Health Dashboard: game-HUD + observability; tiap subsystem → health%, click-through ke modul/file/baris (via ImpactDebugger + packages/editor/CodeNavigator + packages/impact/*).
  • “Repair = commit”:
    1. Damage → DamageResolver identifikasi modul terkait
    2. Dev debug & update code
    3. Commit → ARCLUX re-analyze
    4. VesselModel update → health pulih

​
Layer G — Server/Infra (objek K3)

  • Sebagian besar workload di client/user runtime (render + sebagian sim).
  • Server/global cuma: identity, sync, persistence, world-events, validation, permissions.
  • Persistence pakai packages/db + packages/storage/RecoveryManager.
  • Community/fleet/station/territory/hall-of-fame = milestone lanjutan (lihat docs/blueprint/02-station-infrastructure.md).

​
Layer H — Business & Ecosystem

  • Monetisasi: core sudah arclux live di npm. Tier: free core + premium SDK/MCP/enterprise + storage/history + advanced universe component.
  • Collaborator ecosystem: extension di atas ARCLUX (SDK, sandbox, validation, publish) — tanpa write access ke core. Fondasi ada di packages/shell/plugins.ts + detectors.ts (user-space).

​
Layer I — Combat & World Validator (Anti-Cheat)

Ringkasan — detail penuh di docs/blueprint/03-combat.md.
Visual boleh cinematic. Hasil harus deterministic + tervalidasi. “Users create the machines. ARCLUX defines the physics. The server verifies reality.”
I.1–I.8 — visual serangan (archetype, client-render); damage per-subsystem; catastrophic → wreckage; World Validator (server = referee, validasi tiap request); vessel state fingerprint; component authorization; damage ceiling; replay/event log.

​
3. Roadmap Milestone

​
Milestone 1 — “Kapal Hidup” (pondasi)

1 repo → 1 kapal yang hidup & bisa dijelajah. Validasi loop inti (#2-4, #7-10).
  • .arclux/ schema + generator (arclux connect)
  • World Model core (VesselModel, SystemState, stat mapping, ComponentBinding)
  • Health Dashboard di apps/web (hub 2D)
  • 3D vessel (extend GraphCanvas3D jadi mesh kapal sederhana)
  • License 3-tier validation (LicenseValidator + provenance) — K3
  • Bridge SSE daemon→web (auto-update)
  • arclux connect + docs
Out of scope M1: perang menyeluruh, multi-repo universe, transfer antar kapal, fleet/community, hall-of-fame, global server, station.

​
Milestone 2 — “War & Damage”

  • Damage simulation + DamageResolver + ImpactDebugger
  • Component rusak → capability turun; repair = commit
  • Catastrophic damage threshold → rebuild via commit
  • Multi-repo connect + war 2 kapal (tak merusak repo asli)
  • Combat renderer (visual cinematic) + World Validator (anti-cheat) — Layer I
  • Vessel state fingerprint, component authorization, damage ceiling, replay log
  • Awal spatial navigation antar vessel (zoom ladder dasar, kamera follow) — 01-spatial-ux.md

​
Milestone 3 — “Universe Persisten”

  • Persistent world-state (server sync, identity, events)
  • Transfer component antar kapal + provenance transfer
  • Wreckage Archive + Hall of Fame (museum sejarah) — lihat 04-wreckage-history.md
  • Station awal (outpost/hub dasar: dock, engineering, analysis lab, safe zone) — lihat 02-station-infrastructure.md
  • Semantic navigation penuh (show-in-universe ↔ show-in-code)

​
Milestone 4 — “Ecosystem & Economy”

  • Extension Registry + publish + discovery
  • Community/fleet/station/territory
  • Station evolution (outpost → hub → fleet base / landmark), component market, navigation & security center, observatory
  • Economic loop penuh
  • Spatial zones (open/combat/safe/planetary/travel/special) — ruleset per zone

​
3b. Wreckage & Hall of Fame — Museum Sejarah

Ringkasan — detail penuh di docs/blueprint/04-wreckage-history.md. Kapal yang hancur tidak “respawn lalu hilang”. Ia meninggalkan puing sejarah yang permanen dan menjadi aset dunia. Puing membawa provenance (jejak hidup sebuah component: dibuat → dipasang → dipindah → hancur → recovered → Hall of Fame). Hall of Fame = museum sejarah, bukan leaderboard. Filosofi yang konsisten: ARCLUX tidak perlu membuat semua cerita. Developer & komunitas menciptakan kejadian → ARCLUX menyimpan & memvisualisasikan sejarahnya. Itulah yang membuat ARCLUX terasa seperti dunia, bukan sekadar game yang punya map.

​
4. Yang Sudah Ada vs Harus Dibangun

​
5. Risiko & Pertanyaan Terbuka

  1. Anti-abuse & fairness (K1-C): gimana user extends base-stat tanpa jadi pincang? Butuh rule: override cap / atribut yang tak bisa diubah.
  2. Validasi sentral vs lokal: untuk kompetisi adil, mungkin butuh server validation di M2+ war.
  3. “Perang” perlu attack surface yang adil — tuning supaya tak mudah 1-hit-KO.
  4. Skala visi besar: M1 harus dikunci supaya arsitektur tak melenceng saat ke M2-M4.
  5. Anti-cheat combat: arsitektur “server sebagai referee, client hanya render” mengharuskan world-state yang terpusat & ter-version (fingerprint, replay log) — ini menambah kebutuhan server validation yang lebih kuat dibandingkan M1 single-repo.
  6. Latency & determinism: karena hasil ditentukan server, perlu desain input-queue + event replay agar dua client melihat kejadian konsisten.
  7. Abstraction zoom ladder: seberapa dalam ladder (Universe → … → Code) bersifat tetap vs adaptif terhadap kedalaman repo sebenarnya (lihat 01-spatial-ux.md — Abstraction Zoom System).
  8. Station scale: sistem station harus mendukung ribuan station tanpa jadi monolit — ARCLUX membangun rules, bukan membuat station satu-per-satu (lihat 02-station-infrastructure.md).