Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
324 lines (247 loc) · 11 KB

CONTRIBUTING.md

File metadata and controls

324 lines (247 loc) · 11 KB

Contributing

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.

Language Server

A modified version of YimLLS can be found here. Clone the repo and point to its path in your workspace to have type hints for everything the project adds to the vanilla API.

  • Example .code-workspace or settings.json file:

    {
	"folders": [
		{
			"path": "."
		},
	],
	"settings": {
    "Lua.workspace.checkThirdParty": false,
    "Lua.workspace.library": [
			"MyDrive:\\Path\\To\\YimLLSX"
    ],
    "Lua.runtime.builtin": {
			"debug": "disable",
		},
	}
}

Commit Convention

These are recommended, but not enforced yet. We follow slightly similar commit guidelines to YimMenu:

Commit Structure

<type>(scope): <description>

[optional body]

[optional footer]

  • Types (lowercase only):

    • feat: New features.
    • fix: Bug fixes.
    • style: Feature and updates related to styling.
    • refactor: Refactoring a specific section of the codebase.
    • test: Everything related to testing.
    • docs: Everything related to documentation.
    • chore: Regular code maintenance.

  • Scope:

    • A scope is a phrase describing parts of the code affected by the changes. For example (translations).

  • Body (Optional):

    • The commit body can provide additional contextual information. For breaking changes, the body MUST start with "BREAKING CHANGE".

  • Footer (Optional):

    • A commit footer is used to reference issues affected by the code changes. For example: "Fixes #13". It can also be used to indicate breaking changes by starting with "BREAKING CHANGE".

  • Example:

    fix(SomeFeature): fix constructor returning an empty object.
docs(Readme): document coding conventions

Coding Standards

Annotations

Annotate all enums, classes, and class methods following the Lua Language Server standard.

Annotations are critical for readability, code completion, error checking, and automatic generation of class documentations.

For comments/summaries/descriptions, you can use either 2 or 3 dashes but please leave a space between the last dash and the text.

  • Example:

    -- Calculates the sum of two numbers.
---@param a number The first number
---@param b number The second number
---@return number The sum of both numbers
function MyClass:Add(a, b)
    return a + b
end

Global Variables

There are two ways to declare globals:

  1. Globals that should be serialized to JSON: Index the global GVars table. Even if the variable was never declared before:

    GVars.some_feature_enabled, _ = ImGui.Checkbox("My Checkbox", GVars.some_feature_enabled)

  2. Regular globals: Use Lua's default global table _G:

    some_global_number = 123

Style

You are free to use any style you want, except in these cases:

Scope Naming Example
Global Functions PascalCase function DoSomething(...) end
Local Functions any (consistent) You are free to use any style as long as it stays consistent throughout the whole file
Standard Lib Extensions Use the lib's default style string.somefunc = function(...) end
Enums PascalCase prefixed with a lowercase e eExampleEnum
Enum Members Preferably UPPER_SNAKE_CASE but PascalCase is also allowed eExampleEnum.SOME_MEMBER/eExampleEnum.SomeMember
Classes PascalCase MyNewClass = Class("MyNewClass")
Class Methods PascalCase function MyNewClass:ExampleMethod(...) end
Class Members snake_case prefixed with an m m_handle

Formatting

  • Indentations:

    • Indentation and empty spaces are handled by .editorconfig. Please make sure you have it in your workspace.

  • Line Wrapping:

    • Try to wrap wide lines using either your IDE's formatter or a Pythonic way.

      • Example:

        SomeFunc(param1, param2, param3, param4, param5, param6, param7, param8, param9, ...)

      • Preferred (Pythonic) style:

        SomeFunc(
    param1,
    param2,
    param3,
    param4,
    param5,
    param6,
    param7,
    param8,
    param9,
    ...
)

  • Nested if Statements:

    • Always try to use guarded if statements when applicable.

      • Bad Example:

        local cond_1 = false
local cond_2 = nil
local cond_3 = true

if cond_1 then
    if cond_2 then
        if cond_3 then
            DoSomething()
        end
    end
end

      • Preferred approach:

        local cond_1 = false
local cond_2 = nil
local cond_3 = true

if not cond_1 then
    return
end

if not cond_2 then
    return
end

if not cond_3 then
    return
end

DoSomething()

      • Shorter version:

        local cond_1 = false
local cond_2 = nil
local cond_3 = true

if not (cond_1 and cond_2 and cond_3) then
    return
end

DoSomething()

Macros

The project defines these global macros for convenience:

  • _F -> string.format
  • _J -> joaat.
  • _T -> Translator:Translate

Translations

  • The primary language for all labels is English (US) (includes/lib/translations/en-US.lua).
  • To add a new language, add its ISO code to includes/lib/translations/__locales.lua.
  • To add a new label, update /lib/translations/en-US.lua.
  • All other language files will be automatically generated via GitHub Actions.

Examples

Adding A New Label

Suppose you want to draw some text that gets automatically translated:

  1. Open includes/lib/translations/en-US.lua.

  2. Add a key-value pair for your new label:

    return {
  ...
  ["MY_LABEL"] = "My label's text in English."
}

  3. Use the key with the _T macro:

    ImGui.Text(_T("MY_LABEL"))

Adding A New Language

  1. Open includes/lib/translations/__locales.lua.

  2. Add a new language iso to the array:

    return {
  ..., -- pre-existing strings
  "tr-TR", -- Your new language
}

Project Structure

The project is organized by responsibility rather than feature size. Folders define architectural boundaries and expected usage patterns.

├─ includes/
│  ├─ classes/           # A place where all classes are stored.
│  │  └─ gta/            # Contains reverse-engineered game classes mostly sourced from Yimura's archived repository and others I reversed myself using a mix of debuggers, public research, and personal suffering.
│  │
│  ├─ data/              # A place where all raw data is stored.
│  │  ├─ actions/        # Contains YimActions V3 data (animations, scenarios, synchronized scenes, and movement clipsets).
│  │  └─ enums/          # Groups all game and custom enums in one place under one `Enums` global namespace.
│  │
│  ├─ features/          # Stores all script features.
│  │  ├─ extra/          # Self-contained experience-enhancing features.
│  │  ├─ online/         # Online-only features.
│  │  ├─ self/           # Player-specific features.
│  │  ├─ vehicle/        # Vehicle-specific features.
│  │  └─ world/          # World-specific features.
│  │
│  ├─ frontend/          # This is where UI tabs live. As a contributor, you are free to organize UI source files however you want but this general rule is highly recommended:
│  │                       # - If your UI requires more than one file, group them in a subfolder.
│  │                       # - If you have one large file doing a multitude of things, split it into multiple files and group them in a subfolder.
│  │
│  ├─ lib/               # Serves as the project's library folder.
│  │  ├─ extensions/     # API and standard library extensions.
│  │  └─ translations/   # This is where translation files, supported locales, and the translations hash map are stored.
│  │
│  ├─ modules/           # Contains custom modules such as native wrappers, game entity abstractions, YimMenu API wrappers, and higher-level gameplay utilities.
│  │
│  ├─ services/          # Contains runtime services (GUI, KeyManager, Serializer, CommandExecutor, etc.)
│  │  └─ asset_browsers/ # Stores an assortment of focused asset browsers and their base class.
│  │
│  ├─ structs/           # Stores helper structs.
│  │
│  ├─ thirdparty/        # Thirdparty components and their license texts.
│  │
│  ├─ backend.lua        # Central backend module providing lifecycle coordination, entity management, and API/script version checks.
│  ├─ tests.lua          # Purely for local tests in a mock environment.
│  ├─ version.lua        # This is purely for CI and should never be edited. It stores the latest script version.
│  └─ init.lua           # Initializes the whole project.
│
└─ samurais_scripts.lua  # Main entry point that calls `init.lua`, handles late initialization for a few modules/services, registers commands, and lazily populates a few data sets in a fiber.

Where Does My Code Go?

Addition Home Notes
A gameplay feature includes/features/ Features are behavior, not UI.
A UI tab or layout code includes/frontend/ UI only. No game logic.
A reusable system with lifecycle includes/services/ -
A reverse-engineered game structure or a custom Lua class includes/classes/ -
A lightweight data container or object includes/structs/ No lifecycle, no side effects.
Raw static data (tables, lists, maps) includes/data/ Never execute logic here.
A native wrapper or abstraction includes/modules/ Bridges Lua <-> game engine.
Utility or extension code includes/lib/ Generic helpers and API/stdlib extensions.
Initialization or bootstrapping init.lua / backend.lua Do not add features here.
A third party module from somewhere/someone else includes/thirdparty Place in a subfolder accompanied with the module's license (when applicable).

What To Avoid

  • Manually editing any language file except en-US.lua. They are auto-generated so any changes you add will be overwritten by GitHub Actions.
  • Contributing licensed open source code from other developers without permission, credits, or original license (when applicable).
  • Adding high-risk online options without clear and concise user warnings.