UI Overview

True Life's UI system is built with React 19, Redux Toolkit, and Tailwind CSS. It provides a modern, performant interface for in-game HUDs and pages.

Technology Stack

Technology	Version	Purpose
React	19.2	UI framework with React Compiler
Redux Toolkit	2.11	State management with dynamic slices
Tailwind CSS	3.4	Utility-first styling
shadcn/ui	Latest	Component library
Motion	12.23	Animations
Vite	7.2	Build tool with HMR

Architecture

Feature Types

HUDs

HUDs are small overlays positioned in a 3x3 grid:

HUDs are:

• Always visible during gameplay
• Positioned via hudPosition property
• Stacked by hudPriority within a position

Pages

Pages are full-screen interfaces:

• Open/close via client events
• Block game input when visible
• Used for menus, inventories, etc.

Project Structure

ui/
├── src/
│   ├── main.tsx              # React app entry
│   ├── modules/index.ts      # Feature discovery
│   ├── feature.ts            # defineFeature() API
│   ├── shells/               # Layout containers
│   │   ├── HudShell/         # 3x3 grid HUD container
│   │   └── PageShell/        # Full-screen container
│   ├── components/           # Reusable components
│   │   └── ui/               # shadcn/ui components
│   ├── state/                # Redux state
│   │   ├── featureSlice.ts   # Feature loading state
│   │   └── featureRuntime.ts # Loading/unloading thunks
│   ├── store.ts              # Redux store
│   ├── hooks.ts              # React hooks
│   └── lib/                  # Utilities
├── vite.config.ts
└── tailwind.config.cjs

Development Server

Start the UI dev server with HMR:

pnpm dev:ui
# Runs at http://127.0.0.1:3000

The dev server provides:

• Hot Module Replacement (HMR)
• Mock NUI events for testing
• React DevTools support
• Fast Refresh

Path Aliases

Alias	Path
@ui/*	./ui/src/*
@core/*	./src/lib/*
@modules/*	./src/modules/*

Best Practices

1. Use feature system - Don't bypass for custom UI
2. Keep state in Redux - Don't use component-local state for shared data
3. Use Tailwind utilities - Consistent styling
4. Leverage shadcn/ui - Pre-built accessible components
5. Add animations - Use Motion for polish
6. Optimize bundle size - Dynamic imports for features