Technical Design Documents

Document Information

Version

2.5.0

Status

Approved

Priority

★★★★★ (Critical)

Engine

Roblox Studio

Language

Luau

Last Updated

Juli 2026

Purpose

Dokumen ini menerjemahkan System Boundaries (CDR-007) dan Game Systems Overview menjadi struktur konkret di Roblox Studio Explorer: layanan mana menyimpan script apa, bagaimana sistem dipecah jadi ModuleScript, dan bagaimana server/client dipisah.

TDD-001 adalah fondasi untuk TDD-002 Remote Events & Functions dan TDD-003 DataStore Schema — keduanya merujuk balik ke Module Map di dokumen ini.

Disinkronkan (Version 2.0.0, Juli 2026) — ditemukan lewat audit menyeluruh. Dokumen ini tertinggal di v1.0.0 sepanjang seluruh migrasi besar (Fase A–F dan revisi HP/Consumable), sehingga bertentangan dengan TDD-002: TDD-002 sudah lama mendefinisikan katalog Remote untuk Caravan, sementara Module Map di sini tidak punya CaravanService sama sekali. Lebih parah, tidak ada satu pun Service yang memiliki Stamina — seluruh sistem kondisi pemain tidak punya rumah arsitektural. Kontradiksi antar-dokumen teknis adalah jenis kesalahan yang paling mahal saat implementasi dimulai, karena ia baru ketahuan setelah kode ditulis.

Architecture Pillars

• Server Authority — seluruh state penting (Coin, Inventory, Collection, ownership) hidup dan divalidasi di server. Client hanya mengirim intent dan menampilkan hasil (CDR-007).
• One Module, One System — setiap sistem di Game Systems Overview punya satu ModuleScript server sebagai pemilik state-nya. Sistem lain tidak boleh menulis langsung ke state sistem lain, hanya lewat fungsi publik modul tersebut.
• Data-Driven — tabel MDD diterjemahkan apa adanya menjadi ModuleScript data (mis. AnimalData.lua mengembalikan array record yang kolomnya sama persis dengan MDD-001), bukan logika if/else per spesies (DN-008).
• Boot Once, Init Explicit — satu script Boot memuat seluruh Service secara berurutan saat server start, bukan setiap modul mendaftar dirinya sendiri secara implisit.
• Simple First — MVP memakai state machine dan struktur module sederhana; pola yang lebih rumit (dependency injection, ECS, dsb.) tidak dipakai kecuali kebutuhan nyata muncul (CDR-007, CDR-009).

Roblox Explorer Structure

Struktur ini adalah organisasi script di dalam Roblox Studio — berbeda dari struktur folder dokumentasi proyek di PHDS-003 (yang mengatur dokumen, bukan Instance game).

• ServerScriptService/Services/ — satu ModuleScript per sistem server (lihat Module Map). Tidak bisa diakses client.
• ServerScriptService/Boot.server.lua — satu-satunya Script yang require() dan menjalankan seluruh Service di atas, urutan eksplisit (Persistence & Economy sebelum sistem yang bergantung padanya).
• ServerStorage/GameData/ — ModuleScript data hasil transkrip MDD: AnimalData (MDD-001), WeaponData (MDD-002), ItemData (MDD-003), BiomeData (MDD-004), ProgressionData (MDD-006), TrophyData (MDD-007), PersonalityData (MDD-008) — satu file per MDD, kolom mengikuti MDD apa adanya.
  Dikoreksi v2.0.0: EconomyData dihapus dan TrophyData ditambahkan. MDD-005 tidak lagi menyimpan tabel harga sejak berubah peran menjadi peta sumber harga — mentranskripnya akan menghasilkan file kosong sekaligus menghidupkan kembali duplikasi harga yang justru dicabut. Sebaliknya MDD-007 (Trophy Room, Pedestal, Statue Miniatur) memang punya tabel dan sebelumnya terlewat.
• ReplicatedStorage/Shared/ — ModuleScript yang aman dibaca client & server: constants (Rarity enum, Biome enum), type definitions, fungsi murni yang tidak menyentuh state (mis. formula Coin/Prestige dari MDD-001).
• ReplicatedStorage/Remotes/ — folder RemoteEvent/RemoteFunction, disusun per sistem (lihat TDD-002).
• StarterPlayer/StarterPlayerScripts/Controllers/ — satu LocalScript/ModuleScript Controller per sistem yang butuh logika client (input, feedback, UI wiring). Sistem tanpa kebutuhan client (mis. Persistence) tidak punya Controller.
• StarterGui/Screens/ — UI per layar (HUD, Inventory, Market, Companion, Trophy Room, dst.), dikendalikan oleh Controller terkait.
• Workspace/World/<BiomeName>/ — folder per biome final (Brightmeadow, Hutan, Sungai, Gunung Es, Pantai, Gua, Mistik) berisi SpawnPoint marker, mengikuti landmark GDD-008.
• Workspace/Arena/ — (baru v2.0.0) scene Arena Pembuka untuk sesi pertama pemain baru (GDD-002 Bagian 0). Sengaja di luar World/, karena ia bukan biome: tidak memakai Spawn Weight, tidak memakai sistem biome, dan hewannya diletakkan manual di posisi tetap. Menaruhnya di dalam World/ akan membuat WorldService dan AnimalAIService harus mengecualikannya — satu cabang khusus di dua sistem sekaligus, demi satu scene.

Module Map

Satu baris per sistem di Game Systems Overview. "Server Service" adalah pemilik state; "Client Controller" hanya ada jika sistem butuh logika/feedback di sisi client.

Tiga Service ditambahkan di v2.0.0. Ketiganya bukan sistem baru — ketiganya sudah lama ada di lapisan desain dan hanya belum pernah punya baris di sini.

• PlayerConditionService — pemilik tunggal Stamina, Boost Stamina, dan Stamina Sprint. Sengaja satu Service untuk ketiganya, bukan tiga: ketiganya adalah state kondisi pemain per sesi yang dibaca oleh sistem yang sama (gerak, Sprint, Consumable) dan tidak satu pun disimpan ke DataStore. Memecahnya hanya akan membuat tiga modul saling menulis state satu sama lain — persis yang dilarang pilar One Module, One System.
• CaravanService — menutup kontradiksi dengan TDD-002, yang sudah mendefinisikan RequestSendCaravan, RequestClaimCaravan, RequestFulfillOrderInstant, dan CaravanStateUpdated tanpa ada Service yang memilikinya.
• SocialService — pemilik Leaderboard, halaman Profil, pencarian pemain lewat ID, kunjungan Trophy Room, clan otomatis (maks 50 anggota, Chat Clan lintas server lewat MessagingService) dan Chat Clan lintas server. Tidak ada sistem trading formal — negosiasi terjadi di percakapan atau di luar game, dan pemindahan barang memakai Item Delivery yang sudah ada (GDD-014 Trading Antar Pemain). Satu-satunya Service yang membaca data pemain lain, sehingga seluruh kebutuhan lintas server terkumpul di satu tempat alih-alih tersebar. Seluruh datanya hanya-baca dan boleh tertinggal — diperbarui batch, tidak menggerbangi apa pun, sehingga asumsi TDD-003 soal ketiadaan state lintas server tetap utuh.
• TutorialService — sesi pertama pemain baru kini punya alur yang dikunci isinya dan satu pengecualian resmi terhadap alur baku (Arena Pembuka tanpa layar Loadout, GDD-003). Pengecualian yang tidak dimiliki modul mana pun akan berakhir tersebar sebagai if isNewPlayer di banyak Service — justru bentuk paling rapuh dari apa yang ingin dihindari. Service ini juga pemilik dua hasil yang di-hardcode dan dilarang masuk kalkulasi neraca (1 Crystal Caravan pertama, hasil First Patrol — ECO-015).

Naming Convention

• ModuleScript Service/Controller: PascalCase diakhiri Service (server) atau Controller (client) — mis. EconomyService, InventoryController.
• ModuleScript data mentah di ServerStorage/GameData: PascalCase diakhiri Data — mis. AnimalData, mengikuti prefix ID PHDS-002 (ANM, WPN, MNT, dst.) untuk key record.
• Fungsi publik modul: verb di depan — GetAnimalById, SellAnimal, GrantExp.
• Nama Remote mengikuti konvensi TDD-002 (Request<Verb><Noun> untuk client→server, <Noun><PastVerb> untuk server→client).

MVP Technical Scope

Selaras CDR-007 MVP Technical Scope — seluruh Service di Module Map dibangun untuk sistem yang sudah Final di roadmap. Service untuk item roadmap yang masih "Ide Awal" (Grid Backpack #23, Prestige/Special Mount #27) belum dibuatkan baris Module Map; ditambahkan saat DN masing-masing selesai dirancang.

Dependencies

• CDR-007 — Technical Philosophy.
• GDD-002 — Gameplay Loop (Stamina, Boost Stamina, Tutorial Sequence, Arena Pembuka).
• DN-002 — Player Movement Speed.
• DN-010 — Companion System.
• DN-011 — Caravan Trade Market.
• CDR-008 — Performance Philosophy.
• CDR-009 — Development Philosophy.
• DN-008 — Data-Driven Design + MDD.
• PHDS-002 — Naming Convention & Identifier Standard.
• PHDS-003 — Project Folder Structure Standard.
• game-systems.html — Game Systems Overview.
• TDD-002 — Remote Events & Functions.
• TDD-003 — DataStore Schema.