Karel The Robot - Universal Backend

• 1. General
  • 1.1. Abstract
  • 1.2. Why this project exists?
• 2. Using the PBE
  • 2.1. Downloading a Frontend
  • 2.2. Downloading PBE
  • 2.3. Building PBE
  • 2.4. Maps
• 3. Frontends
  • 3.1. Create your own
  • 3.2. API
    • 3.2.1. Errors
    • 3.2.2. Request (JSON)
    • 3.2.3. Response (JSON)
    • 3.2.4. Commands

1. General

1.1. Abstract

Karel The Robot was invented in th 1970s by Richard E. Pattis at Standford Univeristy. Karel The Robot is a program, that should make the intruduction to coding for newcomers and beginners more simple. Its aim is to teach basic principles such as top-down programming and establish them from the beginning. Futhermore is learning programming with Karel The Robot a way more visual and rewarding experience then just printing out some strings and numbers onto the command-line.

1.2. Why this project exists?

Since its original development in th 1970s many projects have replicated and improved on the originial idea. The biggest drawback of the original Karel The Robot is however, that he has its own programming-language. This is usefull if you primary focus is on establishing programmically thinking, as mentioned above. If there should however be taught a programming language besides that, Karel The Robot had to implemented in this language.

For this reason there is quite a limited number of ports of Karel The Robot to different programming languages. And even if there is a port of Karel The Robot for your programming language, cross system compatablility is quite rare. This is why I started this project. The cross system compatability of Python and pygame covers Linux, MacOS and Windows. The project will feature precompiled versions for all of those systems. Then you can choose a suitable Frontend for your language and if none exists you can easily and fast create one (see 3.1. Create your own).

2. Using the PBE

2.1. Downloading a Frontend

You can find a list of frontend under 3. Frontends. Most frontends will provide a starter project for most systems and IDEs under the releases tab.

2.2. Downloading PBE

If you are creating a frontend or want to update your bundled PBE, than you can download a precompiled version of the PBE for your system under the Releases tab. The downloaded directory will have the following structure. If you want to add maps just place your .xml-files in PBE_PKG/assets/map.

PBE_PKG
├── assets
│   ├── map
│   │   ├── 1x1.xml
│   │   ├── 1x8.xml
│   │   └── ...
│   └── pbe.yaml
├── karel_pbe
└── run_karel_pbe.sh

2.3. Building PBE

# clone the repo and cd into into it
git clone https://github.com/hendrikboeck/karel_the_robot_python3_backend.git
cd karel_the_robot_python3_backend

# create a virtual env and download dependecies
python3 -m venv env
./env/bin/activate
pip install -r requirements.txt

# build the project
pyinstaller karel_pbe.spec

Now you have to create a folder assets in the folder, where you want to execute ./karel_pbe, and copy the file assets/pbe.yaml to your assets folder and your .xml-files into the assets/map folder.

2.4. Maps

New maps can be added by adding the file to the assets/map folder. If you want to create a new map use the following example:

<?xml version="1.0" encoding="UTF-8"?>

<!-- DOCUMENT START -->
<map size="(10, 7)" speed="1.00">

  <!-- METADATA -->
  <metadata name="TestRoom" version="1.0" author="Hendrik Boeck" />

  <!-- MAP OBJECTS -->
  <karel position="(1, 2)" orientation="SOUTH" beeperbag="inf" />
  <wall start="(7, 1)" length="3" orientation="WEST" />
  <wall start="(7, 4)" length="4" orientation="SOUTH" />
  <beeper position="(8, 4)" n="2" />

</map>
<!-- DOCUMENT END -->

3. Frontends

Language	Language Version	Project
Java	11 =<	hendrikboeck/karel_the_robot_java_frontend
C	99 =<	hendrikboeck/karel_the_robot_c_frontend

3.1. Create your own

The project uses a websocket as its communication. It can be configured over the configuration (assets/pbe.yaml) file. The backend supports UDP as well as TCP-sockets. The commands use a variation of JSON-RPC as its format (more accurate information and all the commands can be found under 3.2. API). You dont have to check if an instance of the Karel is already running. The backend will not start if the port is occupied (this also means, do not use a port pre-occupied on your system).

3.2. API

The API uses json-encoded messages inspired by JSON-RPC v2. Every request to the server will need a autoincrementing id for identifying the corresponding response. If the request resembles a Karel-Action (e.g. move) or System-Update (e.g. EOS) the returned type will null; for Karel-Questions (e.g. frontIsClear) the returned type will be a boolean. If an error was thown in the backend the returned type will always be string identifying the error.

3.2.1. Errors

• ActionExecutionError: an Karel-Action could not be performed (e.g. "Karel hit a wall")
• MapLoadingError: map could not found or could not be read correctly
• UnallowedActionError: A command has been received, even though the game is already finished or another error, that was sent early, has been ignored.

3.2.2. Request (JSON)

{
    "id": 0,  // autoincrement
    "function": <functionname>,
    "args": <arguments>  
}

3.2.3. Response (JSON)

{
    "id": 0,  // same id as request
    "result": <return>
}

3.2.4. Commands

loadWorld

loads a mapname.xml file as World into the game. (mapname.xml can eighter be loaded from local file in assets/map/ or from a embedded maps in the exe).

• arguments: dictionary
  • map: string, name of map that should be loaded
• return: null

EOS

terminates command sequence for backend. Has to be called as last command in program.

• arguments: null
• return: null

move

is a Karel-Action. Makes Karel move 1 tile forward in the direction he is looking at. If Karel can not execute move a ActionExecutionError is thrown.

• arguments: null
• return: null

turnLeft

is a Karel-Action. Makes Karel turn left.

• arguments: null
• return: null

pickBeeper

is a Karel-Action. Makes Karel pick a beeper from current position. If Karel can not execute pickBeeper a ActionExecutionError is thrown.

• arguments: null
• return: null

putBeeper

is a Karel-Action. Makes Karel put a beeper at current position. If Karel can not execute putBeeper a ActionExecutionError is thrown.

• arguments: null
• return: null

frontIsClear

is a Karel-Question. Returns wether there is a wall in front of Karel.

• arguments: null
• return: boolean

rightIsClear

is a Karel-Question. Returns wether there is a wall to the right of Karel.

• arguments: null
• return: boolean

leftIsClear

is a Karel-Question. Returns wether there is a wall to the left of Karel.

• arguments: null
• return: boolean

beeperInBag

is a Karel-Question. Returns wether Karel has at least one beeper left in his bag.

• arguments: null
• return: boolean

beeperPresent

is a Karel-Question. Returns wether at least one beeper is present on the position Karel is at.

• arguments: null
• return: boolean

facingNorth

is a Karel-Question. Returns wether Karel is currently facing north.

• arguments: null
• return: boolean

facingEast

is a Karel-Question. Returns wether Karel is currently facing east.

• arguments: null
• return: boolean

facingSouth

is a Karel-Question. Returns wether Karel is currently facing south.

• arguments: null
• return: boolean

facingWest

is a Karel-Question. Returns wether Karel is currently facing west.

• arguments: null
• return: boolean