tommieChat

English | 日本語

Updated: April 1, 2026 (v0.1.11)

Project Status: Currently under active development. An experimental server is available at mmo.tommie.jp.

A 3D MMO chat game that runs in the browser. Built with Babylon.js + Nakama, it provides a real-time multiplayer environment where you can place blocks and chat with others.

Table of Contents

1. Screenshots
2. Features
3. Tech Stack
4. Requirements
5. Setup
6. Port Numbers
7. Controls
8. Directory Structure
9. Documentation
10. Development Tools
11. Contributing
12. License
13. Author

1. Screenshots

Screenshots are from the development version and may change significantly.

Live capture: orbiting the camera around the avatar in the browser-based 3D world — translucent player-placed blocks, grid terrain, and the minimap. Try it at mmo.tommie.jp.

2. Features

• Runs entirely in the browser (no installation required)
• PWA support (installable to home screen for fullscreen experience)
• Real-time chat in a 3D world with speech bubbles
• Sprite-based avatar system
• World editing through block placement
• Supports multiple simultaneous users
• Easy login via device authentication
• Asset storage via MinIO

3. Tech Stack

Component	Technology
3D Engine	Babylon.js 8.x
Game Server	Nakama 3.35
Server Logic	Go
Frontend	TypeScript
Build Tool	Vite
Database	PostgreSQL 16
Object Storage	MinIO
Container	Docker Compose

4. Requirements

Development Environment

• Node.js v24+ (required for frontend build)
• Docker / Docker Compose (required for server startup)

Production Environment

• Docker / Docker Compose only (deploy pre-built dist/)

Browser

• Mobile support (iOS Safari, Android Chrome)
• WebGL 2.0 compatible browsers (Chrome, Edge, Firefox, Safari)

5. Setup

5.1 Clone the Repository

git clone https://github.com/tommie-jp/tommie-chat.git
cd tommie-chat

5.2 Client (Frontend)

npm install
npm run build

5.3 Server (Nakama)

# Set up environment variables
cp nakama/.env.example nakama/.env

# Start the server
cd nakama && docker compose up -d && cd ..

# Build & deploy the Go plugin
bash nakama/doBuild.sh --fresh

5.4 Open in Browser

Open http://localhost (serves dist/ via nginx).

During development, you can also use the Vite dev server (http://localhost:5173) with npm run dev.

Nakama admin dashboard: http://localhost:7351 (default credentials: admin / password)

5.5 Testing

# Type checking
npm run check

# Unit tests
npm test

# Integration tests (run while Nakama server is running)
bash test/doAll.sh

# Lint all files
bash test/doLint.sh

6. Port Numbers

Port	Purpose
80	Web frontend (nginx)
5173	Vite dev server
5432	PostgreSQL
6060	Go pprof profiler
7349	Nakama gRPC API
7350	Nakama client API
7351	Nakama admin dashboard
9090	Prometheus metrics

7. Controls

• Login: Enter a user ID and click the login button
• Move: Click or tap to set a destination
• Place Block: B key + click (mobile: not yet supported)
• Chat: Send messages from the text input at the bottom
• Camera: Drag or swipe to rotate

8. Directory Structure

tommieChat/
├── src/                  # Client-side source code (TypeScript)
│   ├── main.ts           # Entry point
│   ├── GameScene.ts      # Babylon.js game scene
│   ├── NakamaService.ts  # Nakama server communication
│   ├── UIPanel.ts        # UI panels
│   ├── AOIManager.ts     # AOI (Area of Interest) management
│   ├── AvatarSystem.ts   # Avatar management
│   ├── SpriteAvatarSystem.ts # Sprite-based avatar system
│   ├── ChunkDB.ts        # Chunk database
│   ├── CloudSystem.ts    # Cloud effects
│   ├── NPCSystem.ts      # NPC management
│   ├── Profiler.ts       # Performance profiling
│   ├── WorldConstants.ts # World constants
│   └── DebugOverlay.ts   # Debug overlay
├── public/               # Static assets
│   ├── textures/         # Textures (.ktx2)
│   ├── manifest.json     # PWA manifest
│   └── sw.js             # Service Worker
├── nakama/               # Server-side
│   ├── docker-compose.yml
│   ├── go_src/           # Go server plugin (main.go)
│   ├── nginx.conf        # Reverse proxy configuration
│   ├── doBuild.sh        # Plugin build script
│   └── doRestart.sh      # Server restart script
├── test/                 # Test scripts & test code
│   ├── doAll.sh          # Run all tests
│   ├── doLint.sh         # Lint check
│   ├── doNight.sh        # Overnight long-running tests
│   ├── doTest-*.sh       # Various test scripts
│   ├── nakama-*.test.ts  # Vitest test files
│   └── log/              # Test report output
├── docs/                  # Documentation
├── pic/                  # Image assets & conversion scripts
├── .github/              # GitHub Actions / Dependabot
├── index.html            # Main HTML
├── package.json
├── vite.config.ts
├── vitest.config.ts
└── tsconfig.json

9. Documentation

Detailed documentation is available in the docs/ directory.

Document	Description
03-nakama-server-setup	Nakama server setup guide
04-DB-concurrent-connections	Concurrent connection DB design
05-user-ID-deletion	User ID deletion procedure
06-nakama-tuning	Server tuning parameters
07-MinIO-asset-storage	MinIO asset storage
10-frontend-file-structure	Frontend file structure
11-RPC-function-list	Server RPC function list
20-browser-profiling	Browser-side performance profiling
21-nakama-server-profiling	Server-side profiling
30-test-script-list	Test scripts and options
40-deployment-guide	Sakura VPS deployment guide
42-LAN-connection	LAN connection guide
43-mobile-display-test	Mobile display testing
51-SpriteViewer-demo	SpriteViewer demo

10. Development Tools

This project extensively uses Claude Code (Anthropic) for design, implementation, testing, and documentation.

11. Contributing

See CONTRIBUTING.md.

12. License

MIT License

13. Author

• tommie.jp
• X: @tommie_nico