minecraftconsoles-lce

What this skill does

# MinecraftConsoles (Legacy Console Edition) Skill

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

## What This Project Is

MinecraftConsoles is a C++ reimplementation/continuation of **Minecraft Legacy Console Edition v1.6.0560.0 (TU19)**, targeting modern Windows (and unofficially macOS/Linux via Wine). Goals include:

- Multi-platform base for modding, backports, and LCE development
- Quality desktop experience with keyboard/mouse and controller support
- LAN multiplayer and dedicated server software
- Splitscreen multiplayer support

**Repository:** `smartcmd/MinecraftConsoles`  
**Primary language:** C++  
**Build system:** Visual Studio 2022 solution (`.sln`) + CMake support  

---

## Quick Start

### Prerequisites

- **Windows** (primary supported platform)
- [Visual Studio 2022](https://aka.ms/vs/17/release/vs_community.exe) with C++ desktop workload
- Git

### Clone

```bash
git clone https://github.com/smartcmd/MinecraftConsoles.git
cd MinecraftConsoles
```

### Build with Visual Studio

1. Open `MinecraftConsoles.sln` in Visual Studio 2022
2. Set **Startup Project** to `Minecraft.Client`
3. Set configuration to **Debug** (or Release), platform to **Windows64**
4. Press **F5** or **Ctrl+F5** to build and run

### Build with CMake (Windows x64)

```powershell
# Configure
cmake -S . -B build -G "Visual Studio 17 2022" -A x64

# Build the client
cmake --build build --config Debug --target MinecraftClient

# Build the dedicated server
cmake --build build --config Debug --target MinecraftServer
```

See `COMPILE.md` in the repo for additional platform-specific notes.

---

## Running the Client

### Nightly Build (No Compile Needed)

Download the `.zip` from the [Nightly Release](https://github.com/smartcmd/MinecraftConsoles/releases/tag/nightly), extract, and run `Minecraft.Client.exe`.

### Setting Your Username

Create `username.txt` in the same directory as the executable:

```
Steve
```

Or use a launch argument:

```powershell
Minecraft.Client.exe -name Steve
Minecraft.Client.exe -name Steve -fullscreen
```

### Client Launch Arguments

| Argument | Description |
|---|---|
| `-name <username>` | Override in-game username |
| `-fullscreen` | Launch in fullscreen mode |

---

## Keyboard & Mouse Controls

| Action | Key/Button |
|---|---|
| Move | `W` `A` `S` `D` |
| Jump / Fly Up | `Space` |
| Sneak / Fly Down | `Shift` (hold) |
| Sprint | `Ctrl` (hold) or double-tap `W` |
| Inventory | `E` |
| Chat | `T` |
| Drop Item | `Q` |
| Crafting | `C` (tabs: `Q` / `E`) |
| Attack / Destroy | Left Click |
| Use / Place | Right Click |
| Select hotbar slot | `1`–`9` or Mouse Wheel |
| Pause | `Esc` |
| Fullscreen | `F11` |
| Toggle HUD | `F1` |
| Toggle Debug Info | `F3` |
| Debug Overlay | `F4` |
| Toggle Debug Console | `F6` |
| Toggle FPS/TPS view | `F5` |
| Player list / Host Options | `Tab` |
| Accept tutorial hint | `Enter` |
| Decline tutorial hint | `B` |

---

## LAN Multiplayer

LAN multiplayer works automatically on the Windows build:

- Hosting a world **auto-advertises** it on the local network
- Other players discover sessions via **Join Game** menu
- TCP port: **25565** (game connections)
- UDP port: **25566** (LAN discovery)
- Use the **Add Server** button to connect to known IPs
- Username changes are safe — keep `uid.dat` to preserve your data across renames
- Splitscreen players can join LAN/multiplayer sessions

---

## Dedicated Server

### Download Nightly Server Build

[Nightly Dedicated Server](https://github.com/smartcmd/MinecraftConsoles/releases/tag/nightly-dedicated-server)

### Run Directly (Windows)

```powershell
Minecraft.Server.exe -name MyServer -port 25565 -ip 0.0.0.0 -maxplayers 8 -loglevel info
Minecraft.Server.exe -seed 123456789
```

### Server CLI Arguments

| Argument | Description |
|---|---|
| `-port <1-65535>` | Override `server-port` |
| `-ip <addr>` | Override `server-ip` (bind address) |
| `-bind <addr>` | Alias of `-ip` |
| `-name <name>` | Override `server-name` (max 16 chars) |
| `-maxplayers <1-8>` | Override `max-players` |
| `-seed <int64>` | Override `level-seed` |
| `-loglevel <level>` | `debug`, `info`, `warn`, `error` |
| `-help` / `--help` / `-h` | Print usage and exit |

### `server.properties` Configuration

Located in the same directory as `Minecraft.Server.exe`. Auto-generated with defaults if missing.

```properties
server-name=DedicatedServer
server-port=25565
server-ip=0.0.0.0
max-players=8
level-name=world
level-id=world
level-seed=
world-size=classic
log-level=info
white-list=false
lan-advertise=false
autosave-interval=60
```

**Key property notes:**

| Key | Values | Default | Notes |
|---|---|---|---|
| `server-port` | `1–65535` | `25565` | TCP listen port |
| `server-ip` | string | `0.0.0.0` | Bind address |
| `server-name` | string | `DedicatedServer` | Max 16 chars |
| `max-players` | `1–8` | `8` | Player slots |
| `level-seed` | int64 or empty | empty | Empty = random |
| `world-size` | `classic\|small\|medium\|large` | `classic` | New world size |
| `log-level` | `debug\|info\|warn\|error` | `info` | Verbosity |
| `autosave-interval` | `5–3600` | `60` | Seconds between autosaves |
| `white-list` | `true/false` | `false` | Enable whitelist |
| `lan-advertise` | `true/false` | `false` | LAN advertisement |

---

## Dedicated Server in Docker (Linux/Wine)

### Recommended: Pull from GHCR (No Local Build)

```bash
# Start (pulls latest image automatically)
./start-dedicated-server.sh

# Start without pulling
./start-dedicated-server.sh --no-pull

# Equivalent manual command
docker compose -f docker-compose.dedicated-server.ghcr.yml up -d
```

### Local Build Mode (Optional)

Requires a locally compiled `Minecraft.Server.exe`:

```bash
docker compose -f docker-compose.dedicated-server.yml up -d --build
```

### Docker Persistent Volumes

| Host Path | Container Path | Purpose |
|---|---|---|
| `./server-data/server.properties` | `/srv/mc/server.properties` | Server config |
| `./server-data/GameHDD` | `/srv/mc/Windows64/GameHDD` | World save data |

### Docker Environment Variables

| Variable | Default | Description |
|---|---|---|
| `XVFB_DISPLAY` | `:99` | Virtual display number |
| `XVFB_SCREEN` | `64x64x16` | Virtual screen size (tiny, Wine needs it) |

---

## Project Structure (Key Areas)

```
MinecraftConsoles/
├── MinecraftConsoles.sln       # Visual Studio solution
├── CMakeLists.txt              # CMake build definition
├── COMPILE.md                  # Detailed compile instructions
├── CONTRIBUTING.md             # Contributor guide and project goals
├── docker-compose.dedicated-server.ghcr.yml  # Docker (GHCR image)
├── docker-compose.dedicated-server.yml       # Docker (local build)
├── start-dedicated-server.sh   # Quick-start script
├── server-data/
│   ├── server.properties       # Server config (auto-generated)
│   └── GameHDD/                # World save data
└── .github/
    └── banner.png
```

---

## Common C++ Patterns in This Codebase

### Adding a New Key Binding (Keyboard Input)

The project added keyboard/mouse support on top of the original controller-only code. When extending input:

```cpp
// Typical pattern for checking key state in the input handler
// Find the keyboard input processing file and add your key check:

bool isKeyPressed(int virtualKey) {
    return (GetAsyncKeyState(virtualKey) & 0x8000) != 0;
}

// Example: adding a new toggle key
if (isKeyPressed(VK_F7)) {
    // toggle your feature
    myFeatureEnabled = !myFeatureEnabled;
}
```

### Registering a Launch Argument

Follow the existing `-name` / `-fullscreen` pattern:

```cpp
// In the argument parsing section (typically in main or init):
for (int i = 1; i < argc; i++) {
    std::string arg = argv[i];

    if (arg == "-name" && i + 1 < argc) {
        username = argv[++i];
    }
    else if (arg == "-fullscreen") {
        launchFullscreen = true;
    }
    // Add your argument:
    else if (arg == "-myoption" && i + 1 < argc) {
        myOption = argv[++i];