CONTRIBUTING.md

Contributing - OneAnticheat

Table of Contents

• Overview
• File Structure and Require Aliases
  • @client, @server, and @shared Aliases
• Typing Conventions
  • Module and Type Layout
  • Type and Class Formatting
• Variable and Naming Rules
  • Naming Convention
• Immutable Shared Modules
• Miscellaneous Rules
• Example File Structure
• Issues and Pull Requests
• Summary Checklist

Overview

This document defines the procedure, coding standards, type system expectations, project layout rules, and module interaction guidelines for this codebase.

These guidelines exist to ensure consistency, maintainability, and compatibility across the client/server/shared boundary. All contributors must follow them strictly.

File Structure and Require Aliases

@client, @server, and @shared Aliases

• @client must only be used in client-side scripts (scripts under ./src/client/)
• @server must only be used in server-side scripts (scripts under ./src/server/)
• @shared must not be used in source files inside ./src/shared/
  • Doing so results in invalid paths when transformed by Darklua due to shared modules being duplicated on both client and server folders

Typing Conventions

Module and Type Layout

All scripts should follow this order:

1. Type module requires
2. Type definitions
3. Actual logic

Type and Class Formatting

Every type definition or class must use the @class and @type annotations properly.

Use block docstrings (--[=[ ... ]=]) for:

• Class descriptions
• Function documentation
• Field explanations

Example:

--[=[
    @class MyClass

    This class handles X and Y logic.
]=]

Do not:

• Use --!nolint directives unless if it's required for security reasons (e.g. unreference a sensitive token)
• Use (x :: unknown) :: any, or x :: any casts unless there is no other solution (e.g. getmetatable giving out a type error, even though the given value will always be a table).

Variable and Naming Rules

Naming Convention

Element	Convention	Example
Constants	CONSTANT_CASE	local MAX_CLOCK_DELTA = 5
Local variables	camelCase	local isTimeRespected = clockDelta < MAX_CLOCK_DELTA
Function parameters	camelCase	function(shouldSearchTables, ...)
Local functions	camelCase	local function performStartCheckpoint()
Class/Module references	PascalCase	local DetectionManager = {}, local CommonUtilities = require("@shared/CommonUtilities.luau"
Class/Module functions	PascalCase	Person:Greet(), CommonUtilities.WipeTable
Roblox Instances/Services	PascalCase	CoreGui, RunService, ReplicatedStorage, HumanoidRootPart, "Humanoid"

Do not:

• Use snake_case
• Use global variables (unless needed for detection logic)

Immutable Shared Modules

Modules inside ./src/shared/ are duplicated and isolated on both the client and the server.

You must never mutate or write to tables returned by shared modules.

If you attempt to modify their return values, it will not reflect on the opposite execution context.

Bad example:

--// DON'T DO THIS
local SharedFoo = require("@shared/SharedFoo")
SharedFoo.SomeValue = 123 --// Will not sync between client and server

Miscellaneous Rules

• Functions like ReportAnomalyManual must always perform strict signature validation before accepting input
• Shared cryptographic state (e.g. validation seeds) must be derived from deterministic, non-sensitive values unless otherwise required
• Avoid unnecessary allocations inside detection functions (e.g., large table creations, heavy string operations)

Example File Structure

For reference, here's a minimal layout of a compliant Luau module:

local Types = require("@shared/Types/MyTypes")

--[=[
    @class MyManager

    Handles core logic of detection routing.
]=]
export type MyManager = {
    --[=[
        The amount of times that `MyManager::Greet` was called.
    ]=]
    GreetingCount: number,

    --[=[
        Method that greets a given person of name `x`.

        @param x The name of the person to greet.

        @return The greeting, as a string.
    ]=]
    Greet: (x: string) -> string
}

--[=[
    @class MyManager

    Handles core logic of detection routing.
]=]
local MyManager = {} :: MyManager

function MyManager.Greet(x: string): string
    return "Hello, " .. x
end

return MyManager

Issues and Pull Requests

Submitting Issues

Only submit issues that are specific, and relevant to the project.

Include:

• A clear description
• Steps to reproduce (if applicable)
• Expected behavior and actual behavior
• Logs or error messages if available

Issues that are vague or incomplete may be closed without notice.

Opening Pull Requests

Make your changes in a separate branch if you have write access, otherwise make them in a fork, ideally named after the feature or fix

• e.g., for branches: feature/token-verification, fix/auth-race
• e.g., for forks: oneanticheat-feature-token-verification, oneanticheat-fix-auth-race

Then check the following:

• Ensure all code follows the guidelines outlined above
• Include tests or usage examples when applicable
• Use descriptive commit messages and PR titles
• Reference any related issues using Fixes #issueNumber in the PR description
• Do not include unrelated formatting or refactors in a single PR
• Keep your PR scope focused and atomic

All pull requests will be subject to manual review.

Summary Checklist

• Use camelCase for variables, PascalCase for classes/Instances
• Never use @shared in ./src/shared
• Use @client and @server only in correct contexts
• Types and classes are fully typed and documented
• Shared modules are treated as immutable
• File layout follows: types first, logic after
• PRs are focused, atomic, and pass all checks