Skip to content

docs: add SECURITY.md, CONTRIBUTING.md, and Dependabot config #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cryptochris8 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add SECURITY.md, CONTRIBUTING.md, and Dependabot config #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 58 additions & 0 deletions .github/dependabot.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
version: 2

updates:
# Server dependencies
- package-ecosystem: "npm"
directory: "/server"
schedule:
interval: "weekly"
day: "monday"
open-pull-requests-limit: 10
labels:
- "dependencies"
- "server"
reviewers:
- "iamarkdev"
commit-message:
prefix: "deps(server):"

# Client dependencies
- package-ecosystem: "npm"
directory: "/client"
schedule:
interval: "weekly"
day: "monday"
open-pull-requests-limit: 10
labels:
- "dependencies"
- "client"
reviewers:
- "iamarkdev"
commit-message:
prefix: "deps(client):"

# Protocol dependencies
- package-ecosystem: "npm"
directory: "/protocol"
schedule:
interval: "weekly"
day: "monday"
open-pull-requests-limit: 5
labels:
- "dependencies"
- "protocol"
reviewers:
- "iamarkdev"
commit-message:
prefix: "deps(protocol):"

# GitHub Actions (if any)
- package-ecosystem: "github-actions"
directory: "/"
schedule:
interval: "weekly"
labels:
- "dependencies"
- "ci"
commit-message:
prefix: "ci:"
212 changes: 212 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,212 @@
# Contributing to HYTOPIA Game Engine

Thank you for your interest in contributing to the HYTOPIA game engine! This guide will help you get started.

## Table of Contents

- [Getting Started](#getting-started)
- [Development Setup](#development-setup)
- [Project Structure](#project-structure)
- [Making Changes](#making-changes)
- [Submitting a Pull Request](#submitting-a-pull-request)
- [Code Style](#code-style)
- [Testing](#testing)
- [Community](#community)

## Getting Started

This is the publicly available source of the HYTOPIA game engine. Merged contributions are consolidated into a private deployment repository for scheduled releases to [hytopia.com](https://hytopia.com) and the public SDK on npm.

### Prerequisites

- **Node.js** (v18+)
- **npm** (v9+)
- **Bun** (for server builds)
- A modern browser with WebTransport support (Chrome/Edge recommended)

## Development Setup

### 1. Clone the Repository

```bash
git clone https://github.com/hytopiagg/hytopia-source.git
cd hytopia-source
```

### 2. Install Dependencies

```bash
# Server
cd server && npm install

# Client
cd ../client && npm install
```

### 3. Start Development Servers

**Terminal 1 - Game Server** (runs on `localhost:8080` with hot reload):
```bash
cd server && npm run dev
```

**Terminal 2 - Client** (runs on `localhost:5173`):
```bash
cd client && npm run dev
```

### 4. Open the Game

Navigate to `http://localhost:5173` in your browser. Game logic is in `server/src/playground.ts` and hot-reloads on save.

### 5. Testing with SDK Examples

To test server changes against real games:

```bash
# Build server into sdk/
cd server && npm run build

# Run an example
cd ../sdk-examples/<example-name>
npm install && npm run dev
```

## Project Structure

```
hytopia-source/
├── assets/ # Default game assets → @hytopia.com/assets
├── client/ # Browser game client
│ └── src/
│ ├── main.ts # Entry point → Game.instance.start()
│ ├── NetworkManager.ts # WebTransport + WebSocket
│ ├── Renderer.ts # Three.js rendering
│ ├── ChunkMeshManager.ts # Voxel mesh generation
│ └── EntityManager.ts # Entity lifecycle
├── protocol/ # Packet schema definitions → @hytopia.com/server-protocol
├── sdk/ # Git submodule → hytopiagg/sdk (build output)
├── sdk-examples/ # Reference games (FPS, RPG, battle royale, etc.)
└── server/ # Server source → sdk/server.mjs
└── src/
├── index.ts # SDK entry point
├── playground.ts # Dev playground (hot-reload)
├── GameServer.ts # Bootstrap: physics, assets, connections
├── WorldManager.ts # Multi-world support
├── World.ts # Physics, entities, networking per world
├── WorldLoop.ts # 60 Hz game loop
├── Simulation.ts # Rapier3D physics wrapper
└── NetworkSynchronizer.ts # 30 Hz state updates
```

## Making Changes

### Choosing What to Work On

1. **Check open issues** on [hytopiagg/sdk](https://github.com/hytopiagg/sdk/issues) for bugs and feature requests
2. **Check open PRs** on this repository to avoid duplicate work
3. **Start small** - Bug fixes and documentation improvements are great first contributions
4. **Discuss first** - For significant changes, open an issue or discuss in Discord before coding

### Branch Naming

Use descriptive branch names:
- `fix/model-uri-corruption` - Bug fixes
- `feat/rts-camera-mode` - New features
- `docs/contributing-guide` - Documentation
- `perf/chunk-meshing-optimization` - Performance improvements
- `security/input-rate-limiting` - Security enhancements

### Key Architecture Notes

- **Server is authoritative**: All game state lives server-side. Never add game logic to the client.
- **60 Hz physics, 30 Hz network**: The server runs physics at 60 Hz but syncs to clients at 30 Hz.
- **WebTransport preferred**: WebSocket is a fallback. New networking code should support both.
- **No dynamic Three.js lighting**: The client uses custom ambient/block lighting via shader uniforms.
- **Chunks are 16x16x16**: The ChunkLattice system stores blocks in these fixed-size chunks.

## Submitting a Pull Request

### PR Checklist

- [ ] Changes compile without errors (`cd server && npm run build`)
- [ ] Client changes work in browser (`cd client && npm run dev`)
- [ ] Tested with at least one sdk-example
- [ ] No new TypeScript/ESLint warnings introduced
- [ ] PR description explains the "why" not just the "what"
- [ ] Breaking changes are clearly documented

### PR Description Template

```markdown
## What

Brief description of the change.

## Why

Why is this change needed? Link to relevant issues.

## How

Technical approach taken and key decisions made.

## Testing

How was this tested? Which sdk-examples were used?

## Breaking Changes

List any breaking changes to the SDK API (if applicable).
```

## Code Style

### TypeScript
- Use strict TypeScript (`strict: true`)
- Prefer `const` over `let`; avoid `var`
- Use meaningful variable and function names
- Export types alongside their implementations
- Use `interface` for object shapes, `type` for unions/intersections

### Server Code
- All public APIs should have JSDoc comments
- Event handlers should clean up on disconnect
- Physics operations should respect the 60 Hz tick rate
- Network-visible state changes should go through NetworkSynchronizer

### Client Code
- Heavy computation goes in Web Workers (see ChunkMeshManager pattern)
- Avoid creating objects in render loops (use object pools)
- Respect the MeshBasicMaterial constraint - no dynamic Three.js lights

## Testing

### Manual Testing

1. Start the dev server and client
2. Test your changes in the browser
3. Verify with multiple browser tabs (multiplayer)
4. Test with at least one sdk-example:
```bash
cd server && npm run build
cd ../sdk-examples/<example> && npm install && npm run dev
```

### Performance Testing

For performance-sensitive changes:
- Test with large worlds (MapTopia-generated maps are good for this)
- Monitor the server's `Telemetry` output for tick rate drops
- Check browser DevTools Performance tab for client-side regressions
- Use the debug panel WebGL statistics

## Community

- **Discord**: [HYTOPIA Developers](https://discord.gg/hytopia-developers) - Best place for discussion
- **Issues**: [SDK Issues](https://github.com/hytopiagg/sdk/issues) - Bug reports and feature requests
- **Docs**: [Developer Documentation](https://dev.hytopia.com/) - SDK reference and guides

## License

By contributing, you agree that your contributions will be licensed under the MIT License.
88 changes: 88 additions & 0 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
# Security Policy

## Reporting a Vulnerability

The HYTOPIA team takes security seriously. If you discover a security vulnerability in the HYTOPIA game engine, we appreciate your help in disclosing it to us responsibly.

### How to Report

**Please DO NOT file a public GitHub issue for security vulnerabilities.**

Instead, report vulnerabilities via one of these channels:

1. **GitHub Security Advisories**: Use the [private vulnerability reporting](https://github.com/hytopiagg/hytopia-source/security/advisories/new) feature on this repository
2. **Email**: Contact the HYTOPIA team through the [Discord developer channel](https://discord.gg/hytopia-developers) via direct message to a team member
3. **Responsible Disclosure**: If neither channel is responsive within 72 hours, please reach out via the main [HYTOPIA Discord](https://discord.gg/hytopia)

### What to Include

When reporting a vulnerability, please include:

- **Description**: A clear description of the vulnerability
- **Reproduction Steps**: Step-by-step instructions to reproduce the issue
- **Impact Assessment**: What an attacker could achieve by exploiting this vulnerability
- **Affected Components**: Which part of the codebase is affected (client/, server/, protocol/, etc.)
- **Suggested Fix**: If you have ideas on how to fix the issue (optional but appreciated)

### What to Expect

- **Acknowledgment**: We aim to acknowledge receipt of your report within **48 hours**
- **Assessment**: We will assess the severity and impact within **5 business days**
- **Resolution**: Critical vulnerabilities will be prioritized for immediate patching
- **Credit**: We will credit reporters in our changelog (unless you prefer to remain anonymous)

## Scope

The following components are in scope for security reports:

### In Scope
- **Server** (`server/`): Game server logic, physics, networking, authentication
- **Client** (`client/`): Browser client, rendering, input handling, network communication
- **Protocol** (`protocol/`): Packet schemas, serialization, validation
- **Networking**: WebTransport/WebSocket transport security, packet handling
- **Authentication**: Session token handling, PlatformGateway validation
- **Data Storage**: PersistenceManager, player data handling

### Out of Scope
- Third-party services and platforms (Hytopia.com platform infrastructure)
- Social engineering attacks
- Denial of service attacks that require excessive resources
- Issues in dependencies (report these to the upstream maintainer, but let us know)
- Games built using the SDK (report to the game developer)

## Security Architecture

HYTOPIA uses a **server-authoritative architecture** that provides strong security guarantees:

- All game logic executes server-side; clients only send inputs
- Game code is never replicated to clients
- Server validates all player inputs before processing
- Packet schemas are validated using AJV

### Known Security Considerations

1. **Server-Authoritative Model**: The server is the single source of truth. Client-side manipulation cannot affect game state without server validation.

2. **Transport Security**: WebTransport connections use TLS. WebSocket connections should always use WSS in production.

3. **Input Processing**: All client inputs are processed through the server's tick loop at controlled rates.

4. **Session Management**: Sessions are authenticated via PlatformGateway token validation on connection.

## Supported Versions

| Version | Supported |
|---------|-----------|
| Latest main branch | Yes |
| SDK releases (npm) | Yes |
| Older commits | Best effort |

## Security Best Practices for Game Developers

If you're building games with the HYTOPIA SDK:

1. **Never trust client input** - Always validate game-specific logic server-side
2. **Sanitize chat messages** - Use the built-in chat censoring or add your own filters
3. **Rate limit player actions** - Prevent spam and abuse with server-side rate limits
4. **Validate entity interactions** - Check distances, line of sight, and permissions server-side
5. **Protect sensitive data** - Use the PersistenceManager with appropriate access controls