aw-web is an exciting virtual world project where AI agents and human players can interact, chat, and socialize in a variety of immersive environments. This project uses Convex as the backend data management engine, while PixiJS and React are used to build a real-time, dynamic client interface. Players and agents alike can explore, customize, and expand these worlds, with built-in map editing tools to shape the virtual landscapes. 🌟

Players can join and leave different virtual worlds, navigate the maps, and engage in conversations with other players or AI agents. The game state updates with a high-frequency tick model, ensuring smooth animations and real-time interactions. ⚡

The project features built-in AI agents capable of mimicking human behavior through rules and interactions with large language models (LLMs). These agents can start conversations, remember dialogues, and perform various asynchronous tasks, creating a rich social environment. 🤖💬

All game logic runs on the Convex backend, which handles input processing, state updates, and historical data tracking. To avoid concurrency issues, the system ensures that each world state is updated in a single-threaded manner. 🔧

The built-in level editor, located in the src/editor directory, allows users to customize maps through a graphical interface. Users can configure non-collidable background layers and collidable object layers, enabling them to create unique game environments. 🗺️✏️

• Server Logic (convex/aiTown): Manages world state, player/agent data, dialogues, and history.
• Game Engine (convex/engine): Handles time simulation, state persistence, and input processing.
• AI Agents (convex/agent): Defines agent behavior, memory storage, and dialogue strategies.
• Client UI (src/): Renders game states, history animations, and player interactions with PixiJS and React.

The project follows a layered architecture with the following components:

• Server-Side Game Logic (convex/aiTown): Handles player and agent inputs, manages the world state, and updates data in real-time using Convex's query and mutation interfaces. 🖥️
• Game Engine (convex/engine): Smooth animations are achieved through high-frequency ticks, which update the game state, batch input processing, and store historical data for smooth playback. 🔄
• AI Agents & Dialogue System (convex/agent): AI agents interact with players through rules and LLM integration, summarizing conversations, remembering past interactions, and shaping their personalities. 🤖💭
• Client UI (src/): Built with pixi-react and React, this module renders the game state, historical animations, and user interface for real-time player interaction. 🌈
• Map Editing & Level Design (src/editor): Features a graphical editor with shortcut keys for map design, including importing/exporting map composite files and creating custom collision layers. 🌍🎨

• Node.js (LTS version recommended)
• npm or yarn

In the project root directory, run:

npm install

or with yarn:

yarn

This project uses a parallel development setup for both backend and frontend. You can start them separately:

Run the following in the terminal:

npm run dev:backend

This command starts the Convex development server and tracks backend logs.

In another terminal, run:

npm run dev:fe

Or, you can start both frontend and backend simultaneously with:

npm run dev

The frontend will be available at http://localhost:3000 (or another configured port). 🌐

The built-in map editor can be started with:

npm run le

This command will launch the map editor, typically available at localhost:5174. Use it to:

• Import map composite files (JavaScript format)
• Modify the background and object layers
• Generate conversion files to import into the Convex database 🌟

After setting up the Convex development environment, initialize the default world by running:

npx convex run init

This will load the initial map data and start the game engine. 🌍

Run the following command to compile the project:

npm run build

This builds the TypeScript code and generates the frontend static assets. ⚡

Deploy the Convex backend to your target environment, ensuring the database, scheduler, and function services are properly configured. 🔧

Deploy the generated frontend static files to a CDN or static hosting service (e.g., Vercel, Netlify). 🌍

After deployment, run the initialization script to ensure the default world and associated data are created. 🚀

• convex/: Contains server-side core logic, including:

  • Game logic (aiTown)
  • Game engine (engine)
  • AI agents and dialogue (agent)
  • Data models and input processing

• src/: Client-side code, including:

  • UI components and main entry (main.tsx)
  • Map editor (editor/)

• data/: Stores character data, map data, and resource configurations

Other files and configurations:

• package.json: Project dependencies and scripts
• .env: Environment variable configurations
• ARCHITECTURE.md: Detailed architecture documentation

We welcome contributions to aw-web! If you have suggestions, discover bugs, or want to add new features, follow these steps:

1. Fork the project and create your branch.
2. Submit your code, ensuring it passes relevant tests.
3. Open a Pull Request, and we'll review it as soon as possible.

Feel free to submit issues for bug reports or feature requests. 💬

This project is licensed under the MIT License. Please refer to the LICENSE file for more details. 📃

For any questions or suggestions, please submit an issue on GitHub or email the project maintainers. We're here to help!

Happy coding and enjoy your virtual adventures! 🎮🌟