Contribute
GearN Server is an open-source game backend built with Node.js and TypeScript. Contributions are welcome when they make the server more correct, stable, documented, secure, or useful for real game projects.
The best contributions are practical: they solve a real issue, fit the existing architecture, and are small enough to review safely.
Bug FixesDocumentationPerformanceSecurityTestsExamples
Repository
Start by reading the source and opening a small, focused issue or pull request.
Code Contributions
- Fix bugs in request handlers, services, middleware, startup, or database utilities.
- Improve performance where there is measurable overhead.
- Add missing validation where bad input can break predictable server behavior.
- Keep changes compatible with existing HTTP and socket flows.
Documentation
- Improve setup guides, configuration docs, and deployment notes.
- Add clear API examples for Unity, C#, TypeScript, JavaScript, Java, or Cocos Creator.
- Clarify entity behavior, permission rules, CloudScript, and dashboard workflows.
- Fix broken English, outdated paths, and confusing explanations.
Ideas And Feedback
- Report real production pain, not only abstract feature ideas.
- Describe your game flow, expected behavior, current workaround, and risk.
- Suggest dashboard improvements that reduce support or LiveOps mistakes.
- Share integration issues from real clients and deployment environments.
Before Opening A Pull Request
- Confirm the change belongs in GearN core, not only in one private game project.
- Keep the PR focused on one issue or one feature.
- Follow the existing module boundaries: startup, middleware, handler, service, database, common contracts.
- Update documentation when behavior, configuration, routes, or public contracts change.
- Explain the test or manual verification you performed.
Local Development
Useful local commands in the server repository:
| Install | npm install |
| Build | npm run build |
| Debug | npm run debug |
| Type Check | npx tsc -p tsconfig.json --noEmit |
Project Areas
| Area | Common Files | Contribution Focus |
|---|---|---|
| Startup | src/GN-startup | Runtime assembly, settings, Express, Socket.IO, upload, cluster, middleware. |
| API Handlers | src/GN-app-api/handler | Request parsing, operation routing, entity operations, response data. |
| Services | src/GN-app-api/service | Reusable business workflows, external integrations, CloudScript support. |
| Common Contracts | src/GN-common | Enums, request/response contracts, helpers, constants, operation codes. |
| Database Library | src/GN-library/xdatabase | Entity models, MongoDB object helpers, persistence behavior. |
| Docs | README.md DEVELOPMENT.md ARCHITECTURE.md | Setup, architecture, domain relationships, CloudScript, examples. |
Good Issue Report
- Server version or commit.
- Expected behavior and actual behavior.
- Minimal reproduction steps.
- Relevant config section, request route, role, operation code, or socket event.
- Logs or screenshots when they help explain the failure.
Contribution Principles
- Correctness first: do not hide errors or make silent fallback behavior.
- Compatibility matters: avoid breaking existing clients unless the change is intentional and documented.
- Small PRs win: smaller changes are easier to review and safer to merge.
- Production mindset: consider data safety, security, performance, and observability.
- Respect existing architecture: do not introduce new patterns unless the current structure cannot solve the problem cleanly.