Civilisation DApp

Civilisation DApp is a decentralized application (DApp) for a village-building game. It is designed to run within the World App WebView and provides an engaging gameplay experience with resource management, unit training, and strategic planning.

Features

• Frontend: React + Vite SPA with Zustand stores backed by repository persistence.
• Worldchain connectivity: wagmi + viem for read-only calls, MiniKit sendTransaction for writes (gas-sponsored inside the World App WebView).
• UX preferences: Async-persisted Zustand store using IndexedDB keeps theme, tutorial state, and volume per device.
• Smart contracts: OpenZeppelin-powered diamond architecture deployed to Worldchain.
• Storybook integration: Component-driven development with Storybook.

Project Structure

The project is organized as follows:

• assets/: Contains images for buildings, resources, and units.
• configs/: JSON configurations for game entities like buildings, resources, and units.
• contracts/: Smart contracts for the game, including deployment and configuration scripts.
  • src/core: Diamond proxy, initializer, and shared interfaces/protocols migrated from the legacy src.bak tree.
  • script/: Foundry deployment helpers wired to the new core layout.
• public/: Static assets for the application.
• src/: Source code for the frontend, including components, hooks, and state management.

Development

Codespaces & Dev Containers

Launch the repository inside GitHub Codespaces or VS Code with the Dev Containers extension to use the bundled environment under .devcontainer/. It provisions Bun, Node.js 20, and Foundry, installs dependencies automatically, and exposes the Vite (5173) and Storybook (6006) ports.

Manual setup

To get started with development on a local machine:

1. Install dependencies:

   bun install

2. Start the development server:

   bun run dev

3. Run Storybook for component development:

   bun run storybook

Deployment

The application is designed to be deployed within the World App WebView. Ensure all configurations are set correctly before deployment.

Documentation

The complete documentation set lives in the docs/ directory and is mirrored to the GitHub wiki. Start with the documentation index and explore topic-specific guides:

• Project overview
• Getting started
• Frontend architecture
• Smart contracts
• Worldchain architecture & best practices
• CI/CD workflows

Contributing

Contributions are welcome! Please follow the code of conduct and submit pull requests for review.

License

This project is licensed under the MIT License. See the LICENSE file for details.