https://github.com/beyond-immersion/bannou-service
The all-purpose .NET monoservice for the Beyond Immersion game servers.
https://github.com/beyond-immersion/bannou-service
cloud-services csharp docker dotnet game-backend game-development game-server game-services gamedev goap goap-planner matchmaking microservices multiplayer npc-ai nswag openapi openresty realtime websocket
Last synced: 5 days ago
JSON representation
The all-purpose .NET monoservice for the Beyond Immersion game servers.
- Host: GitHub
- URL: https://github.com/beyond-immersion/bannou-service
- Owner: beyond-immersion
- License: mit
- Created: 2023-02-16T09:13:54.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2026-01-26T08:00:09.000Z (8 days ago)
- Last Synced: 2026-01-26T20:59:08.163Z (8 days ago)
- Topics: cloud-services, csharp, docker, dotnet, game-backend, game-development, game-server, game-services, gamedev, goap, goap-planner, matchmaking, microservices, multiplayer, npc-ai, nswag, openapi, openresty, realtime, websocket
- Language: C#
- Homepage: https://beyond-immersion.com
- Size: 16.3 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Bannou Service
[](https://github.com/beyond-immersion/bannou-service/actions/workflows/ci.unit.yml)
Bannou is a schema-driven monoservice platform for multiplayer games. It provides a WebSocket-first edge gateway with zero-copy message routing, plugin-based service architecture, and abstracted infrastructure (lib-state, lib-messaging, lib-mesh). Designed to support Arcadia, a revolutionary MMORPG with 100,000+ AI-driven NPCs, Bannou scales from a single development machine to distributed production clusters without code changes.
## Quick Start
```bash
# 1. Clone
git clone https://github.com/beyond-immersion/bannou-service.git
cd bannou-service
# 2. Install dev tools (.NET 10, NSwag, Python, Node.js)
./scripts/install-dev-tools.sh
source ~/.bashrc
# 3. Build and verify
make quick
# 4. Start the stack
make up-compose
# 5. Verify it's running
curl http://localhost:8080/health
```
**Next steps:** See the [Quickstart Guide](docs/guides/QUICKSTART.md) for client/service integration, or the [Getting Started Guide](docs/guides/GETTING_STARTED.md) for a comprehensive walkthrough.
## Documentation
### Getting Started
| I want to... | Time | Guide |
|--------------|------|-------|
| **Get running quickly** | 5 min | [Quickstart](docs/guides/QUICKSTART.md) |
| **Full setup walkthrough** | 30 min | [Getting Started](docs/guides/GETTING_STARTED.md) |
| **Connect a game client** | 15 min | [Client Integration](docs/guides/CLIENT_INTEGRATION.md) |
| **Make service-to-service calls** | 10 min | [SDKs Overview](docs/guides/SDKs.md) |
### Development
| I want to... | Read... |
|--------------|---------|
| Understand the architecture | [Bannou Design](docs/BANNOU_DESIGN.md) |
| Add or extend a plugin | [Plugin Development Guide](docs/guides/PLUGIN_DEVELOPMENT.md) |
| Understand a specific service | [Plugin Deep-Dives](docs/plugins/) (41 services) |
| Run and write tests | [Testing Guide](docs/guides/TESTING.md) |
| Contribute code | [Development Rules](docs/reference/TENETS.md) |
### Operations
| I want to... | Read... |
|--------------|---------|
| Deploy to production | [Deployment Guide](docs/guides/DEPLOYMENT.md) |
| Understand CI/CD pipelines | [GitHub Actions](docs/operations/GITHUB_ACTIONS.md) |
| Set up NuGet publishing | [NuGet Setup](docs/operations/NUGET_SETUP.md) |
## Key Features
- **WebSocket-First**: Connect service edge gateway with 31-byte binary headers for zero-copy routing
- **Schema-Driven**: OpenAPI specs generate controllers, models, clients, and tests—you write only 18-35% of the code
- **Plugin Architecture**: Each service is an independent assembly, loadable via environment config
- **Infrastructure Abstraction**: Portable infrastructure (databases, messaging, service mesh) via lib-state, lib-messaging, and lib-mesh
- **Monoservice Flexibility**: Same binary deploys as monolith or distributed microservices
## Essential Commands
```bash
# Development
make build # Build all projects
make generate # Regenerate services from schemas
make format # Fix formatting and line endings
# Testing
make test # All unit tests
make test-http # HTTP integration tests
make test-edge # WebSocket edge tests
make test-ci # Full CI pipeline locally
# Docker
make up-compose # Start local stack
make down-compose # Stop and cleanup
```
## Technical Specifications
- [WebSocket Protocol](docs/WEBSOCKET-PROTOCOL.md) - Binary protocol specification
- [Schema Rules](docs/reference/SCHEMA-RULES.md) - OpenAPI schema authoring reference
- [Permissions System](docs/X-PERMISSIONS-SPECIFICATION.md) - Role-based access control schema
- [Service Details](docs/GENERATED-SERVICE-DETAILS.md) - Service descriptions and API endpoints
- [Events Reference](docs/GENERATED-EVENTS.md) - Auto-generated event documentation
- [Configuration Reference](docs/GENERATED-CONFIGURATION.md) - Environment variables
- [State Stores](docs/GENERATED-STATE-STORES.md) - Redis/MySQL state stores
## Project Structure
```
bannou-service/
├── schemas/ # OpenAPI specifications (source of truth)
├── plugins/lib-*/ # Service plugins (41 services)
├── bannou-service/ # Main application and shared code
├── sdks/ # SDK packages (C#, TypeScript, Unreal)
│ ├── core/ # Shared types (BannouJson, ApiException, base events)
│ ├── server/ # Server SDK (mesh clients, behavior runtime)
│ ├── client/ # Client SDK (WebSocket, typed proxies, events)
│ ├── client-voice/ # Voice communication SDK
│ ├── bundle-format/ # .bannou archive format (LZ4 compression)
│ ├── asset-*/ # Asset loading/bundling (client, server, Stride, Godot)
│ ├── scene-composer-*/ # Scene composition (core, Stride, Godot)
│ ├── music-*/ # Music generation (theory, storyteller)
│ ├── typescript/ # TypeScript client SDK
│ └── unreal/ # Unreal Engine integration
├── tools/ # Testing and inspection tools
│ ├── http-tester/ # HTTP integration test framework
│ ├── edge-tester/ # WebSocket edge test framework
│ └── bannou-inspect/ # Assembly inspection CLI
├── examples/ # Example projects and demos
├── docs/ # Documentation
├── provisioning/ # Docker and deployment configs
└── scripts/ # Code generation and build scripts
```
## Community
- **Discord**: [Beyond Immersion](https://discord.gg/3eAGYwF3rE) - Discussion, questions, and collaboration
- **GitHub Issues**: Bug reports and feature requests
- **GitHub Discussions**: Questions and broader conversations
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Please note that this project follows a [Code of Conduct](CODE_OF_CONDUCT.md).
## License
This project is licensed under the [MIT License](LICENSE).