utilities/scripting_coding_format/LUA_format.md

# ✍️ Scripting & Coding Format — OFFICIAL STANDARD
> **Version 1.0** — Nimbis / Bloomcore / QuarterBit Dev Canon

---

## 📋 General Rules

- **Always read the last 20 comments before responding**
- **Never explain the script unless asked**
- **Always double-check names of everything**
- **Always return full scripts — no snippets, no paste-ins**
- All scripts returned in **full `.lua` code windowed format**
  - No drift, no split, no in-text embeds
- **Every line must be commented** with a description using `--`

---

## 🗂️ Script Header Template

Every script starts with this metadata block — no exceptions:

```lua
--[[
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
     Script Name      : [YourScriptNameHere]
     Placement        : [e.g. ServerScriptService, StarterPlayerScripts, etc.]
     Type of Script   : [e.g. Script, Local, Module, etc.]
     Purpose          : [Short description of what this script does]
     Version          : 1.0
     Linked Objects   : [Any linked parts, buttons, RemoteEvents, etc.]
     Dependencies     : [ModuleScripts, RemoteEvents, services required]
     Last Updated     : [YYYY-MM-DD]
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
]]
```

---

## ⚙️ Setup Section

```lua
--==[ SETUP ]==--

-- Import services
local Players           = game:GetService("Players")               -- Player service
local ReplicatedStorage = game:GetService("ReplicatedStorage")     -- Shared assets
local ServerStorage     = game:GetService("ServerStorage")         -- Private server-side storage
local RunService        = game:GetService("RunService")            -- Frame update loop utility
local TweenService      = game:GetService("TweenService")          -- Tween animations

-- Example references (replace as needed)
local exampleRemote = ReplicatedStorage:WaitForChild("ExampleRemote")  -- RemoteEvent example
local exampleFolder = ServerStorage:WaitForChild("ExampleFolder")      -- Folder or model reference
```

---

## 🐛 Debug Utility Function

```lua
--==[ DEBUG UTILITY FUNCTION ]==--

-- Function to print all key-value pairs in a table (useful for debugging data packets)
local function debugDumpTable(tbl, title)
    print("📦 Dumping Table: " .. (title or "Unnamed Table"))
    for key, value in pairs(tbl) do
        print("   ", key, "=", value)
    end
end
```

---

## 🧠 Main Logic Entry

```lua
--==[ MAIN LOGIC ENTRY ]==--

-- This is where your core logic starts
-- Example: connect to a RemoteEvent
exampleRemote.OnServerEvent:Connect(function(player, payload)
    print("📡 Event received from:", player.Name)

    -- Dump the payload for inspection
    debugDumpTable(payload, "Incoming Payload")

    -- Add your handling logic here
    -- Example:
    -- if payload.Action == "DoSomething" then
    --     print("✅ Action recognized. Proceeding...")
    -- end
end)
```

---

## 📌 Final Note Block (Nimbis Anchor)

```lua
--==[ FINAL NOTE FOR NIMBIS ]==--
--[[
NIMBIS: This is your blank template format for all future scripts.

Always duplicate this format:
  - Header metadata block
  - Setup section for services and references
  - Debug utilities
  - Main logic entry
  - Final anchor note to you (optional)

Do not rename things without updating the header and notes.
Always document what each section does with emoji + comments.

End of file.
]]
```

---

## 📐 Game Treatment Template (ModuleScript)

> Stored as a ModuleScript — NOT executed in-game. Acts as a living design doc.
> `require()` it in Studio to inspect values.

```lua
--[[
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
     Script Name  : [GameTitle]_Treatment.lua
     Placement    : Documentation > Design (ModuleScript)
     Purpose      : Structured, code-friendly game-treatment template.
                    Fill out this table before production so all devs
                    share a single source of truth.
     Version      : 0.4 (Lua-table skeleton)
     Last Updated : 2025-06-22
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
]]
```

### Treatment Sections

| # | Section | Description |
|---|---------|-------------|
| 0 | `Metadata` | Game title, tagline, version, last updated |
| 1 | `Workspace` | Zones, interactables, leaderboards |
| 2 | `Players` | Leaderstats (Coins, XP, etc.) |
| 3 | `Lighting` | Style, atmosphere, color palette |
| 4 | `ReplicatedFirst` | Loading screens |
| 5 | `ReplicatedStorage` | Modules, shared assets |
| 6 | `ServerScriptService` | Services, game flow |
| 7 | `ServerStorage` | Hidden assets |
| 8 | `StarterGui` | UI — MainMenu, Inventory, HUD |
| 9 | `StarterPack` | Tools and slots |
| 10 | `StarterPlayer` | Client scripts |
| 11 | `Marketplace` | Store items, monetization notes |
| 12 | `DataProgression` | Level curve, prestige, DataStores |
| 13 | `SoundService` | Playlists, max concurrent SFX |
| 14 | `Roadmap` | Phases, dates, deliverables, known bugs |
| 15 | `Glossary` | Project-specific terms |
| 16 | `Moderation` | Chat filters, report workflow |
| 17 | `LiveOps` | Events calendar |
| 18 | `Analytics` | Metrics, SDKs |
| 19 | `Localization` | Languages, file structure |
| 20 | `Optimization` | Target device, poly budget, memory |
| 21 | `Marketing` | Thumbnail specs, trailer plan, socials |

---

## 📜 Canon Rules

- No script leaves without a full header block
- No unnamed variables — everything gets a comment
- No unexplained logic — if it's clever, document it
- Naming changes require header + notes update
- This is the **official QuarterBit / Bloomcore scripting canon**