📖 English 📖 中文

🧩 A Forge mod that runs a WebSocket server on the Minecraft client (single-player / LAN), allowing external applications to execute commands and interact with the game in real time.

💡 How it works — When you play single-player or open to LAN, your client runs an integrated server underneath — the same command engine, world ticking, and gameplay loop as a dedicated server.

☝️🤓 In Minecraft, "single-player", "multiplayer", "LAN", and "server" all run the same server code — there's no essential difference. LCon taps into this integrated server and starts a WebSocket server alongside it, so external tools can control the game without needing a separate dedicated server.

LCon starts a WebSocket server inside your Minecraft client when you're in a world (single-player or LAN). You can connect to it from any WebSocket client — a Python script 🤖, a chatbot 💬, a web dashboard 📊 — and:

✅ No Mixin, no coremod, no overwrites — purely event-driven, safe for any modpack.

1. Download the latest .jar from Releases
2. Place it in your client's mods/ folder
3. Launch Minecraft — lcon-ws-server.toml is auto-generated in config/ on first load

⚠️ mods/ and config/ must be at the same directory level.
Typical structure: .minecraft/mods/lcon-*.jar + .minecraft/config/lcon-ws-server.toml

uv venv --python 3.13
uv pip install websocket-client
uv run python -c "
import websocket; ws = websocket.create_connection('ws://localhost:58115?token=your_secret_token')
while True:
  msg = ws.recv(); print(msg)
  if '✅' in msg or 'ready' in msg: break
ws.send('[server]/say awa!'); print(ws.recv()); ws.close()
"

npx wscat -c ws://localhost:58115?token=your_secret_token

Once connected, you'll receive welcome messages from the server:

< 🎉 200:Welcome to LCon! Have fun! Don't forget to use prefixes with every message you send to me.
< 📋 200:Valid prefixes:
< 💬 200:[chat] - send message to Minecraft chat.
< 📩 200:[message] - display message for player only.
< 🔔 200:[system] - display system message in chat (for player only).
< 🖥️ 200:[client] - execute client-side command.
< 🖧 200:[server] - execute server-side command.
< ✅ 201:ready.

Then send commands with prefixes (> is what you type, < is the server response):

> [server]/say Hello everyone!
# (command executed — no response text, but the chat message appears in-game)

> [chat]Hello!
# (message sent as the player in chat)

> [server]/give @s diamond 64
# (command executed — diamonds appear in your inventory)

> unknown-qwq
< ❌ 400:Error! Send message prefix first! [chat], [message], [system], [client], [server] are valid prefixes.

A Textual-based terminal UI with tabbed interface (Console, Commands, Settings, About).

git clone https://github.com/VincentZyuApps/lcon.git
cd lcon

uv venv --python 3.13
uv pip install textual websocket-client

uv run python ./client/main.py

Copy the example and edit:

cp config/.env.example config/.env

Priority: environment variable → config/.env → hardcoded default.

bash (Linux / macOS / WSL / Git Bash):

LCON_HOST=192.168.1.100 LCON_PORT=58115 LCON_TOKEN=your_secret_token
uv run python client/main.py

PowerShell (Windows):

$env:LCON_HOST="192.168.1.100"; $env:LCON_PORT="58115"; $env:LCON_TOKEN="your_secret_token"
uv run python client/main.py

CMD (Windows):

set LCON_HOST=192.168.1.100 && set LCON_PORT=58115 && set LCON_TOKEN=your_secret_token
uv run python client/main.py

File: .minecraft/config/lcon-ws-server.toml

💡 When using the Python TUI client, set serializer_mode = "json" in lcon-ws-server.toml for best compatibility.

💡 For mclistener command execution, keep command_tracking_mode = "single" unless you explicitly want best-effort parallel tracking.

./gradlew build

📦 Output: build/libs/lcon-*.jar

Push to any branch with specific keywords in the commit message:

git commit -m "fix: something; build action"
git commit -m "feat: something; build release"

Dependency	Version	Description
	17	Runtime
	47.2.19	Mod loader
	8.1.1	Build tool
	7.1.0	Fat-jar plugin
	1.5.6	WebSocket server (fat-jarred)
	—	GitHub CI/CD

Dependency	Version	Description
	3.13	Runtime
	≥8.2	TUI framework
	≥1.9	WebSocket client