|
1 | | -# Commit Convention |
| 1 | +# Contributing |
| 2 | + |
| 3 | +Thank you for considering contributing to this project! It's people like you that make the open source community a great place to learn, inspire, and create. |
| 4 | + |
| 5 | +## Commit Convention |
2 | 6 |
|
3 | 7 | These are recommended, but not enforced yet. We follow slightly similar commit guidelines to [YimMenu](https://github.com/Mr-X-GTA/YimMenu/blob/master/CONTRIBUTING.md): |
4 | 8 |
|
@@ -82,7 +86,7 @@ Use Lua's default global table `_G`: |
82 | 86 | You are free to use any style you want, except in these cases: |
83 | 87 |
|
84 | 88 | | Scope | Naming | Example | |
85 | | -| ----------- | ----------- | ---------- | |
| 89 | +| :---: | :---: | :---: | |
86 | 90 | | Global Functions | PascalCase | `function DoSomething(...) end` | |
87 | 91 | | Local Functions | any (consistent) | You are free to use any style as long as it stays consistent throughout the whole file | |
88 | 92 | | Standard Lib Extensions | Use the lib's default style | `string.somefunc = function(...) end` | |
@@ -220,6 +224,59 @@ Suppose you want to draw some text that gets automatically translated: |
220 | 224 | } |
221 | 225 | ``` |
222 | 226 |
|
| 227 | +## Project Structure |
| 228 | + |
| 229 | +The project is organized by responsibility rather than feature size. Folders define architectural boundaries and expected usage patterns. |
| 230 | + |
| 231 | +```bash |
| 232 | +├─ includes/ |
| 233 | +│ ├─ classes/ # Contains reverse-engineered game classes (mostly sourced from Yimura's archived classes repository) and a few Lua-defined classes. |
| 234 | +│ │ |
| 235 | +│ ├─ data/ # A place where all raw data is stored. |
| 236 | +│ │ ├─ actions/ # Contains YimActions V3 data (animations, scenarios, synchronized scenes, and movement clipsets). |
| 237 | +│ │ └─ enums/ # Groups all game and custom enums in one place under one `Enums` global namespace. |
| 238 | +│ │ |
| 239 | +│ ├─ features/ # Stores all script features. |
| 240 | +│ │ ├─ self/ # Player-specific features. |
| 241 | +│ │ ├─ vehicle/ # Vehicle-specific features. |
| 242 | +│ │ └─ world/ # World-specific features. |
| 243 | +│ │ |
| 244 | +│ ├─ frontend/ # This is where UI tabs live. |
| 245 | +│ │ |
| 246 | +│ ├─ lib/ # Contains project libraries and commands: API extensions, translations, Lua standard library extensions, global utilities, etc. |
| 247 | +│ │ |
| 248 | +│ ├─ modules/ # Contains custom modules such as native wrappers, game entity abstractions, and higher-level gameplay utilities. |
| 249 | +│ │ |
| 250 | +│ ├─ services/ # Contains runtime services (GUI, KeyManager, Serializer, CommandExecutor, etc.) |
| 251 | +│ │ |
| 252 | +│ ├─ structs/ # Stores helper structs. |
| 253 | +│ │ |
| 254 | +│ ├─ thirdparty/ # Thirdparty components and their license texts. |
| 255 | +│ │ |
| 256 | +│ ├─ backend.lua # Central backend module providing lifecycle coordination, entity management, and API/script version checks. |
| 257 | +│ ├─ version.lua # This is purely for CI and should never be edited. It stores the latest script version. |
| 258 | +│ └─ init.lua # Initializes the whole project. |
| 259 | +│ |
| 260 | +└─ samurais_scripts.lua # Main entry point that calls `init.lua`, handles late initialization for a few modules/services, and lazily populates a few data sets in a fiber. |
| 261 | +``` |
| 262 | + |
| 263 | +## Where Does My Code Go? |
| 264 | + |
| 265 | +| Addition | Home | Notes | |
| 266 | +| :---: | :---: | :---: | |
| 267 | +| A gameplay feature | `includes/features/` | Features are behavior, not UI. | |
| 268 | +| A UI tab or layout code | `includes/frontend/` | UI only. No game logic. | |
| 269 | +| A reusable system with lifecycle | `includes/services/` | Must be explicitly initialized. | |
| 270 | +| A reverse-engineered game structure or a custom Lua class | `includes/classes/` | - | |
| 271 | +| A lightweight data container or object | `includes/structs/` | No lifecycle, no side effects. | |
| 272 | +| Raw static data (tables, lists, maps) | `includes/data/` | Never execute logic here. | |
| 273 | +| A native wrapper or abstraction | `includes/modules/` | Bridges Lua `<->` game engine. | |
| 274 | +| Utility or extension code | `includes/lib/` | Generic helpers and API/stdlib extensions. | |
| 275 | +| Initialization or bootstrapping | `init.lua` / `backend.lua` | Do not add features here. | |
| 276 | +| A third party module from somewhere/someone else | `includes/thirdparty` | Place in a subfolder accompanied with the module's license *(when applicable)*. | |
| 277 | + |
223 | 278 | ## What To Avoid |
224 | 279 |
|
225 | 280 | - Manually editing any language file except `en-US.lua`. They are auto-generated so any changes you add will be overwritten by GitHub Actions. |
| 281 | +- Contributing licensed open source code from other developers without permission, credits, or original license *(when applicable)*. |
| 282 | +- Adding high-risk online options without clear and concise user warnings. |
0 commit comments