VSCode Hamster Simulator

The VSCode Hamster Simulator is a Visual Studio Code extension that brings the classic "Java-Hamster-Modell" directly into your editor. It provides an interactive webview grid where a simulated hamster can move, turn, pick up grains, and avoid walls.

This extension acts as the visual frontend and WebSocket server, designed to be controlled remotely by external programming libraries like PyHamsterLink.

📸 In Action

🚀 Features

• Interactive Webview: A fully rendered grid containing the hamster, walls, and grains right beside your code.
• WebSocket Communication: Runs an external WebSocket server on port 8200 to receive commands from your scripts, and an internal server on port 8080 to communicate with the webview UI.
• Adjustable Speed: Includes a UI slider to control the execution speed of the simulation in real-time.
• Dynamic Territory Loading: Capable of loading complete grid layouts (walls, grains, hamster position) on the fly via JSON/.ter file data.

📦 Installation & Setup

If you are cloning the repository to run or modify the extension yourself, follow this exact workflow:

1. Open the Project: Clone the repository and open the root VSCodeHamsterExtension folder in Visual Studio Code.
2. Install Dependencies: Open the integrated terminal (Ctrl + Shift + Ö) and run:

   npm install

3. Compile the Code: In the same terminal, compile the TypeScript into JavaScript by running:

   npm run compile

4. Launch the Extension Host: Go to the top menu and click Run > Run Without Debugging (Ctrl + Shift + Ö). This will open a brand new VS Code window labeled [Extension Development Host].
5. Open the Command Palette: Inside that new testing window, open the Command Palette (Ctrl + Shift + P).
6. Start the Simulator: Type Hamster - Simulator and press Enter. The interactive grid will automatically open in a split-view panel next to your editor.
7. Control the Hamster: Run your Python script utilizing the PyHamsterLink library. You can run this script directly from your original VS Code window, a separate system terminal, or any other IDE on your device. It will connect to the extension and execute your commands!

PyHamsterLink Command Reference

German Command	English Command	Action Description
verbinden()	connect()	Establishes the WebSocket connection to the VS Code extension.
ladeTer(datei)	load_ter(file)	Loads a specific territory (.ter) file to set up the grid, walls, and grains.
vor()	move_forward()	Moves the hamster one tile forward. Throws an exception if blocked by a wall.
linksUm()	turn_left()	Rotates the hamster 90 degrees to the left.
nimm()	pickup()	Picks up a single grain from the current tile. Throws an exception if the tile is empty.
gib()	drop()	Drops a single grain onto the current tile. Throws an exception if the hamster's mouth is empty.
vornFrei()	is_front_free()	Checks if the tile directly in front of the hamster is free of walls (Returns True/False).
kornDa()	is_grain_there()	Checks if there is at least one grain on the hamster's current tile (Returns True/False).
maulLeer()	is_mouth_empty()	Checks if the hamster currently has zero grains in its mouth (Returns True/False).
trennen()	disconnect()	Closes the WebSocket connection to the VS Code extension.

🧩 Requirements

• PyHamsterLink installed

Another example

All example scripts can be found in /examples