# Rublox Player

Open-source web player for Rublox games — a Roblox-like creator platform.

Built with **Babylon.js 7** + **React 18** + **Vite 5**. Plays user-created 3D games published from [Rublox Studio](https://git.rublox.pro/rublox/studio) (separate repo).

[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](./LICENSE)
[![Commercial license available](https://img.shields.io/badge/Commercial-License--available-green.svg)](./LICENSE-COMMERCIAL.md)

---

## Quick start (5 minutes)

**Requirements:**
- Node.js 18+ and npm 10+
- A WebGL2-capable browser (Chrome 90+ / Firefox 90+ / Safari 15+)
- 4 GB RAM free (Babylon scenes are heavy)

**Install:**
```bash
git clone ssh://git@git.rublox.pro:2222/rublox/player.git
cd player
npm install
cp .env.example .env       # defaults point at public staging — works out of the box
npm run dev
```

Open `http://localhost:5173/<gameId>` — for example `http://localhost:5173/265` for our GD demo level.

**Without a JWT** you'll see an auth-redirect screen. To bypass for local development:
1. Get a 90-day test JWT from a project maintainer (or use your own from rublox.pro).
2. In browser DevTools console:
   ```js
   localStorage.setItem('player_jwt', '<paste-your-jwt-here>');
   location.reload();
   ```

---

## Assets (GLB models / textures / sounds)

The `public/kubikon-assets/` folder (~106 MB) is **not stored in git** to keep the repo small. Download it separately:

```bash
# Download assets bundle from the latest release:
curl -L -o assets.zip https://git.rublox.pro/rublox/player/releases/download/latest/kubikon-assets.zip
unzip assets.zip -d public/
```

In standalone mode (see below) you don't need the assets — only the bundled sample game runs.

---

## Standalone mode (no backend needed)

Don't have a JWT? Want to try the player without any auth?

```bash
echo "VITE_STANDALONE=true" >> .env
npm run dev
```

Open `http://localhost:5173/sample` — loads a bundled demo project (`src/fixtures/sample-game.json`). All save/leaderboard/chat actions are no-ops.

---

## Project structure

```
src/
├── engine/           # Babylon.js engine — 81 files, ~46k lines.
│                     # Self-contained: BabylonScene, GameRuntime, MultiplayerSync,
│                     # PlayerController, BlockManager, DecoManager, ScriptSandbox,
│                     # 30+ GD (Geometry Dash) gamemode classes.
├── KubikonPlayer/    # Player container UI: menu, chat, comments, mobile controls.
├── editor-shared/    # HUD components shared with editor: hotbar, healthbar, GUI overlay.
├── AdminPreview/     # Preview routes for designer team (skins / music / portals catalogs).
├── PreviewSkin/      # Routes /_preview-skin/<id> etc. used by team.rublox.pro 3D previews.
├── components/       # Shared UI: EmailConfirmNotice, KubikonBugReport, Leaderboard.
├── api/              # API.js (config) + Kubikon3DService.js (endpoint wrappers).
├── auth/             # PlayerAuth.jsx (JWT/ticket flow), ticketExchange.js.
├── hooks/            # useDeviceType.js (mobile/tablet detection).
├── utils/            # kubikonTime.js (relative time formatting).
├── App.jsx, main.jsx, LoadingScreen.jsx
└── fixtures/         # sample-game.json for VITE_STANDALONE=true
```

For deep architecture, see [ARCHITECTURE.md](./ARCHITECTURE.md).

---

## Environment variables

Copy `.env.example` to `.env` and edit:

| Variable | Default | Description |
|---|---|---|
| `VITE_API_BASE` | _(empty)_ | HTTP API base URL. Empty = use vite proxy (dev). |
| `VITE_REALTIME_HTTP` | `https://dev-api.rublox.pro/api-game` | Colyseus HTTP endpoint (multiplayer matchmaking). |
| `VITE_REALTIME_WS` | `wss://dev-api.rublox.pro/api-game` | Colyseus WebSocket endpoint. |
| `VITE_RUBLOX_HOME` | `https://rublox.pro/app` | Where to redirect users with no auth. |
| `VITE_STANDALONE` | `false` | Skip API, load `sample-game.json`. |
| `VITE_API_PROXY_TARGET` | `https://dev-api.rublox.pro` | (dev only) vite-proxy target for `/api-*`. |

---

## Contributing

We welcome PRs! Before your first contribution:

1. Read [CONTRIBUTING.md](./CONTRIBUTING.md) for code style, branch naming, PR template.
2. Sign our [CLA](./CLA.md) — required before any merge (we use a CLA bot in Gitea).
3. Open issues for bugs / feature requests via the templates in `.gitea/ISSUE_TEMPLATE/`.

**Quick PR cycle:**
```bash
git checkout -b feature/your-feature
# ...code...
npm run lint
npm run format
git commit -m "feat: add foo"
git push origin feature/your-feature
# Open PR at https://git.rublox.pro/rublox/player
```

---

## Common tasks

```bash
npm run dev         # Start dev server (vite, port 5173)
npm run build       # Production build → build/
npm run preview     # Preview production build locally
npm run lint        # ESLint
npm run format      # Prettier (write)
npm run format:check  # Prettier (check only — used in CI)
```

---

## License

Dual-licensed:

- **[AGPL-3.0-or-later](./LICENSE)** for open-source use. Forks and derivative works (including network-distributed services) MUST publish their source under the same license.
- **[Commercial License](./LICENSE-COMMERCIAL.md)** for proprietary use. Contact `maksimivankov26@yandex.ru`.

All contributors must sign the [CLA](./CLA.md) before their first merge.

© 2026 Иванкова Виктория Сергеевна (ИП). All rights reserved.

---

## Links

- Main site: https://rublox.pro
- Player demo: https://player.rublox.pro
- Studio (separate repo): https://git.rublox.pro/rublox/studio
- Issues & PRs: https://git.rublox.pro/rublox/player
- Security: see [SECURITY.md](./SECURITY.md)