Flamework for Roblox-TS - Claude Code Skill

A comprehensive skill for working with Flamework, the TypeScript game framework for Roblox.

Overview

Flamework is an extensible TypeScript game framework for Roblox that provides singletons, dependency injection, networking, and a component system with minimal boilerplate.

What This Skill Covers:

• Core Framework: Services, controllers, dependency injection, lifecycle events

• Networking: Type-safe RemoteEvents and RemoteFunctions with automatic guard generation

• Components: Entity-component system with attributes and lifecycle support

• Configuration: Complete project setup, tsconfig.json, and runtime configuration

• Macros: Compile-time utilities like Flamework.id, createGuard, and hash

• Modding: Creating custom decorators, metadata system, and extending Flamework

Documentation Source: Based on official Flamework documentation (https://flamework.fireboltofdeath.dev/) - current as of Flamework v1.0+

Quick Start

Basic Service/Controller

import { Service, OnStart } from "@flamework/core";

@Service() export class MyService implements OnStart { onStart() { print("Service started!"); } }

Dependency Injection

import { Service } from "@flamework/core"; import { OtherService } from "./other-service";

@Service() export class MyService { // Dependencies injected via constructor constructor(private otherService: OtherService) {}

method() {
    this.otherService.doSomething();
}

}

Runtime Initialization

// runtime.server.ts or runtime.client.ts import { Flamework } from "@flamework/core";

// Preload paths (services, controllers, components) Flamework.addPaths("src/server/services/"); Flamework.addPaths("src/server/components/");

// Start the framework Flamework.ignite();

Core Concepts

Singletons

Services (@Service) run on server, Controllers (@Controller) run on client. Only one instance created per class. Load order determined automatically by dependencies or via loadOrder option.

Lifecycle Events

Implement interfaces to hook into lifecycle: OnStart , OnInit , OnTick , OnPhysics , OnRender (client only). Prefer OnStart over OnInit (OnInit blocks sequential execution).

Dependency Resolution

Use constructor DI (preferred) or Dependency<T>() macro. Framework automatically determines load order from constructor dependencies.

When to Use This Skill

• Setting up Flamework project structure

• Creating services, controllers, or components

• Implementing networking with type-safe RemoteEvents/RemoteFunctions

• Using dependency injection patterns

• Working with lifecycle events

• Configuring Flamework (tsconfig.json, flamework.json)

• Using Flamework macros (Flamework.id, Flamework.createGuard, etc.)

• Extending Flamework with custom decorators

Detailed Documentation

This skill uses progressive disclosure for efficient context usage:

• SKILL.md (this file): Quick reference and common patterns (always loaded)

• Reference files: Detailed documentation (loaded only when needed)

Available Reference Files:

• QUICKSTART.md - Complete setup guide for new projects

• CORE.md - Services, controllers, dependency injection, lifecycle events

• NETWORKING.md - RemoteEvents, RemoteFunctions, middleware, type guards

• COMPONENTS.md - Component system, attributes, configuration

• CONFIGURATION.md - tsconfig.json, flamework.json, project setup

• MACROS.md - Utility macros and compile-time features

• MODDING.md - Creating custom decorators, metadata system

Usage Tips

This skill activates when you mention Flamework-related concepts:

• "Create a Flamework service with dependency injection"

• "Set up RemoteEvents for combat system"

• "Make a health component with regeneration"

• "Configure Flamework for production"

• "Use Flamework.createGuard to validate data"

• "Create a custom decorator"

For best results:

• Be specific about what you're building (service, component, networking, etc.)

• Mention Flamework explicitly to trigger the skill

• Ask for complete examples when learning new concepts

• Request configuration help when setting up projects

• Use progressive queries - start general, then ask for specific details

Common Patterns

Service with Dependencies

@Service() export class PlayerService implements OnStart { constructor( private dataService: DataService, private components: Components ) {}

onStart() {
    // Initialize after dependencies ready
}

}

RemoteEvent Communication

// shared/networking.ts import { Networking } from "@flamework/networking";

interface ClientToServer { requestData(id: string): void; }

interface ServerToClient { updateData(id: string, data: unknown): void; }

export const GlobalEvents = Networking.createEvent<ClientToServer, ServerToClient>();

// server/networking.ts export const Events = GlobalEvents.createServer();

// client/networking.ts export const Events = GlobalEvents.createClient();

Component with Attributes

import { Component, BaseComponent } from "@flamework/components";

interface Attributes { health: number; maxHealth: number; }

@Component({ tag: "Health" }) export class HealthComponent extends BaseComponent<Attributes> implements OnStart { onStart() { print(Health: ${this.attributes.health}/${this.attributes.maxHealth}); } }

Installation Quick Reference

Install Flamework

npm i -D rbxts-transformer-flamework npm i @flamework/core

Optional modules

npm i @flamework/networking npm i @flamework/components

tsconfig.json requirements:

{ "compilerOptions": { "experimentalDecorators": true, "plugins": [{ "transform": "rbxts-transformer-flamework" }], "typeRoots": ["node_modules/@rbxts", "node_modules/@flamework"] } }

default.project.json requirements:

{ "node_modules": { "@rbxts": { "$path": "node_modules/@rbxts" }, "@flamework": { "$path": "node_modules/@flamework" } } }

Best Practices

• Use constructor DI over Dependency<T>() macro when possible

• Prefer OnStart over OnInit for lifecycle events

• Split networking into separate server/client files to hide server config from client

• Use progressive disclosure - Split large codebases with clear separation

• Leverage type guards - Flamework auto-generates guards for networking and components

• Structure by feature not by type (group related services/controllers/components together)

Troubleshooting

"Dependency called before ignition" - Use constructor DI or move Dependency() call after Flamework.ignite()

Components not loading - Check ancestorBlacklist/Whitelist, ensure CollectionService tag is set, verify instanceGuard passes

Network type guard failures - Ensure types are supported by guard generation, check middleware configuration

Load order issues - Let automatic resolution handle it, or specify loadOrder in decorator options

For detailed troubleshooting and advanced topics, see the reference documentation files.

Skill Coverage

Complete Flamework v1.0+ Feature Set: ✅ Core singletons and DI

✅ Lifecycle events (OnStart, OnTick, OnPhysics, OnRender)

✅ Full networking module with middleware

✅ Complete component system with attributes

✅ Configuration and setup (tsconfig, flamework.json)

✅ All utility macros (id, implements, createGuard, hash)

✅ Modding and extension API

Best Practices Emphasized:

• Constructor DI over Dependency() macro

• OnStart over OnInit for initialization

• Type safety with automatic guard generation

• Separate server/client networking files for security

• Feature-based code organization

• Progressive disclosure in large codebases