The High-Performance Visualization Engine for AI-Driven Simulations.
Caosmos UI is the official frontend companion for the Caosmos Engine. While the engine handles the complex AI cognition, spatial logic, and simulation physics, this dashboard provides a high-performance, real-time visualization layer.
It is designed to be used in tandem with the backend engine to provide developers, researchers, and users with a deep look into the autonomous behavior of AI "Citizens" within the simulated world.
Designed with Clean Architecture principles and built for extreme performance, Caosmos UI leverages PixiJS for smooth 2D rendering and React 19 for a modern, responsive interface.
Warning
Project Status: Experimental This interface is currently in an experimental phase. It is designed as a basic visualization tool to observe and debug the events occurring within the Caosmos simulation. Features and layout may change frequently.
Click to view application screenshot
- 🛰️ Real-time Map Visualization: High-performance 2D viewport using PixiJS, capable of rendering thousands of entities, zones, and environmental effects.
- 🧠 Cognition Monitoring: Visualize the internal thought processes, goal hierarchies, and decision-making logic of AI agents in real-time.
- 👤 Citizen Insights: Detailed tracking of individual agents, including vitality status, inventory, equipment, and movement history.
- 🌍 World State Tracking: Monitor environmental conditions, time cycles, and dynamic zone interactions.
- 📊 Data Analytics: Integrated charts and metrics for simulation-wide performance and population health.
- 🛠️ Interaction Tools: Directly influence the simulation through a dedicated command and control interface.
- Framework: React 19
- Build Tool: Vite 6
- Language: TypeScript
- Rendering Engine: PixiJS 8
- Styling: Tailwind CSS 4
- State Management: Zustand & React Query
- Data Flow: Immer for immutable state updates.
The project follows a strict Clean Architecture pattern to ensure maintainability and testability:
core: Pure domain logic and entity definitions. No external dependencies.data: Data providers, mappers, and API implementations.presentation: UI components, hooks, and PixiJS renderers.store: Global state management using Zustand.shared: Utilities and common types.
The easiest way to run Caosmos UI in a production-ready environment is using Docker.
- Ensure you have Docker and Docker Compose installed.
- Run the following command to build and start the container:
docker compose up -d --build
- The UI will be available at
http://localhost:5173(by default).
You can customize the deployment using environment variables:
| Variable | Description | Default |
|---|---|---|
PORT |
The host port where the UI will be accessible. | 5173 |
VITE_API_BASE_URL |
The URL of the running Caosmos Engine API. | http://localhost:8080 |
If you prefer to run the project directly on your machine without Docker:
git clone https://github.com/alexpicode/caosmos-ui.git
cd caosmos-ui
npm installCreate a .env file based on .env.example and configure your VITE_API_BASE_URL.
Important
This UI requires a running instance of the Caosmos Backend to function.
npm run devTo generate a static build in the dist/ folder:
npm run buildWe welcome explorers and architects! To get started, please read our Contributing Guide.
- Open an issue for discussion before starting major changes.
- Submit a PR for bug fixes or new features.
If you have any questions, suggestions, or would like to collaborate, feel free to reach out:
📧 Email: alexpicode@proton.me
Built with ❤️ for the AI community by alexpicode