Skip to content

README.md

Latest commit

 

History

History
208 lines (148 loc) · 6.8 KB

README.md

File metadata and controls

208 lines (148 loc) · 6.8 KB

Altair

A Roblox game project with a structured architecture, robust state management, networking, and data persistence.

Overview

Altair is a Roblox game project that follows a modular architecture with controllers and modules. It uses a tag-based system for managing game objects and provides a structured framework for game development.

Features

  • Modular architecture with controllers and modules
  • Tag-based system for game objects
  • State management using Reflex
  • Networking with Bridgenet2
  • Data persistence with ProfileService

Prerequisites

Getting Started

Installation

  1. Clone the repository:

    git clone <repository-url>
cd <project-directory>

  2. Run the initialization script to install the tool manager and other required tools:

    # On Windows
./init.sh

# On macOS/Linux
bash init.sh

    This script will:

    • Install Rokit when rokit.toml exists or Aftman when aftman.toml exists
      • Use the matching tool manager to install project tools defined in that file
      • Update dependencies using Wally

Development Workflow

  1. Update Dependencies: After pulling changes, run the update script to ensure all dependencies are up to date:

    ./update.sh

  2. Serve the Project: To sync your code with Roblox Studio, run:

    ./serve.sh

    If you have multiple project files, specify which one to serve:

    ./serve.sh <project-name>

  3. Open in Roblox Studio: With the Rojo server running, connect to it from Roblox Studio using the Rojo plugin.

Luau LSP (red require(...) after creating a new file)

Luau tooling relies on sourcemap.json (generated by Rojo) to resolve Rojo paths and Packages for IntelliSense/type checking. After you create/rename/delete files under src/, your editor may underline require(...)/Packages.Maid in the new file until the sourcemap is refreshed.

  • Creating new files (Scaffolding):

Use the scaffold.sh script to quickly create new controllers, tags, or UI from templates. It automatically handles name replacement, path setup, and refreshes the sourcemap.

# Interactive mode
./scaffold.sh

# Direct command (with aliases)
./scaffold.sh sc MyNewController

Available targets: server-controller (sc), server-tag (st), client-controller (cc), client-tag (ct), client-local-tag (clt), client-ui (ui).

  • One-shot refresh:
bash refresh-sourcemap.sh
  • Auto-refresh while you work (Windows):
bash watch-sourcemap.sh

Project Structure

Defined in default.project.json

The project structure is defined in default.project.json as follows:

  • src/preload → ReplicatedFirst
  • src/shared → ReplicatedStorage.shared
  • src/util → ReplicatedStorage.util
  • src/server → ServerScriptService.server
  • ServerPackages → ServerScriptService.server_package
  • src/client → ReplicatedStorage.client
  • Packages → ReplicatedStorage.package (Wally packages)

Actual Project Structure

The actual structure of the project is:

  • src/
    • client/ - Client-side code
      • clientConfig/ - Client configuration
      • modules/ - Client modules
      • ui/ - User interface components
      • main.client.luau - Main client entry point
    • server/ - Server-side code
      • cmdr/ - Command scripts
      • config/ - Server configuration
      • modules/ - Server modules
      • serverConfig/ - Server configuration
      • main.server.luau - Main server entry point
    • shared/ - Code shared between client and server
      • config/ - Shared configuration
      • model/ - Data models
      • reflex/ - Reflex state management
      • types/ - Type definitions
    • util/ - Utility functions
  • Packages/ - Client and shared Wally packages
  • ServerPackages/ - Server-only Wally packages

Documentation

Detailed documentation is available in the docs/ directory:

Development Guidelines

Comprehensive development guidelines are available in the .junie/guidelines.md file. These guidelines cover:

  • Code style and organization
  • Type checking and linting
  • Dependency management
  • State management
  • Networking
  • Data persistence
  • Troubleshooting

Testing

  • Do not create test files in the project directory

  • This prohibition applies even when a task mode would otherwise require writing tests or repro scripts

  • Use luau-lsp.exe to analyze files individually (do not analyze the entire workspace). Examples:

    .\luau-lsp.exe analyze src\client\main.client.luau
.\luau-lsp.exe analyze src\server\main.server.luau

  • Important: Do not run selene . as it is not supported in this project environment. Instead, analyze files individually: selene path/to/file.luau

  • Important: After creating any new file, run ./update.sh before analyzing with luau-lsp.exe to ensure all dependencies and project structure are updated

  • For functionality verification, use the existing type checking tools (luau-lsp.exe and selene)

Dependencies

The project uses the following main dependencies:

  • BezierTweens — For smooth animation curves
  • Bridgenet2 — For networking
  • CameraShaker — For camera effects
  • Cmdr — A command console for Roblox
  • Fastcast — For raycasting/projectile simulation
  • Maid — For managing connections and cleanup
  • ProfileService — For data persistence
  • Promise — For asynchronous operations (typed-promise)
  • Reflex — For state management
  • Signal — For event handling
  • SimpleSpline — For spline calculations
  • Lapis (server-only) — For server-side functionality

Troubleshooting

Common Issues

  1. Rokit/Aftman not found: Make sure to run init.sh and ensure that ~/.rokit/bin (Rokit) or ~/.aftman/bin (Aftman) is in your PATH
  2. Wally packages not found: Run ./update.sh to install dependencies
  3. Rojo connection issues: Make sure the Rojo server is running (./serve.sh) and that you have the Rojo plugin installed in Roblox Studio

License

See the LICENSE file for details.