File	Date	Author	Commit
data	2024-05-14	Lee Harr	[d2e957] add level
lib	2024-05-20	Lee Harr	[a23bb1] fix checking variable level solutions
.hgignore	2019-01-25	Lee Harr	[0a47d4] ignore fingerprint/points records
.hgtags	2012-06-17	Lee Harr	[a669c0] Added tag vbot-0.3 for changeset 0fe12597c44e
.tar-ignore	2019-06-21	Lee Harr	[242e13] fix starting scoreserver
COPYING	2010-04-24	Lee Harr	[44ca10] add copyright info
README	2020-03-19	Lee Harr	[2e2203] switch to sourceforge urls
TODO	2020-03-19	Lee Harr	[3de40e] fix level scaling issues
announce	2020-03-19	Lee Harr	[2e2203] switch to sourceforge urls
make_deb.py	2019-06-20	Lee Harr	[c7cd90] better name
setup.cfg	2019-06-18	Lee Harr	[2c60fd] continue setting up .deb and ppa build
setup.py	2020-03-19	Lee Harr	[2e2203] switch to sourceforge urls
vbot	2024-05-14	Lee Harr	[d7cdb4] expose hashdebug from start script

Read Me

vBot is a visual programming game. Use a small set of
command tiles to build a program. The program must
control the vBot and make it activate every target
using the limited command set and limited space.

https://sourceforge.net/projects/vbot-game/

See the Wiki for screenshots:
https://sourceforge.net/p/vbot-game/wiki/Home/


INSTALL:
    There is no support for installing yet. Run the
    program directly from the unpacked archive.

    First, make sure all dependencies are installed
    (See DEPENDENCIES below) then proceed to RUNNING.


RUNNING:
    Run the program from the command prompt like this:

        python3 main.py


PLAYING:
    Drag program tiles from the bottom right to the spaces above.
    (A double-click will send the tile to the next available space.)

    When your program is ready, press the play button (>).

    If there is a problem, rewind (<<), reprogram, and retry.

    GOAL:
        Activate all blue target squares on the level.

        Move robot to blue target squares using the forward, turn left,
            and turn right program tiles. Robot can also jump up or down
            (ONE tile thickness only) using the jump tile.

        When on top of a blue target square use the ! tile to activate.

    FUNCTIONS:
        Some levels provide additional program space in the form of
            functions f1() or f2()

        Jump in to functions by using the F1 or F2 tiles. When the
            function finishes, control returns to the next tile in
            the calling function.

        Try to create functions that can be used repeatedly in
            your program.

    LOOPS:
        Some levels introduce the concept of loops -- N and W.

        N-loops run a set of instructions a given NUMBER of times.
            Choose the number with the mouse wheel over the N tile.
            Select the set of instructions to repeat by dragging
                down from the corner of the N tile. (or press Tab)

        W-loops run a set of instructions WHILE a condition is true.
            Choose the condition with the mouse wheel over the W tile.
            Select the set of instructions to repeat by dragging
                down from the corner of the W tile. (or press Tab)

DEPENDENCIES:
    Python 3:
        https://python.org/
            (tested with python-3.7.3)

    PyQt 5:
        https://www.riverbankcomputing.co.uk/software/pyqt/
            (tested with python3-pyqt5-5.11.3)

    QtSvg 5:
        http://pyqt.sourceforge.net/Docs/PyQt5/QtSvg.html
            (tested with python3-pyqt5.qtsvg-5.11.3)

    QScintilla 2:
        https://www.riverbankcomputing.com/software/qscintilla/
            (tested with python3-pyqt5.qsci-2.10.4)

DEVELOPMENT:
    vBot is released under GPLv3.

    please report any problems here:
        https://sourceforge.net/p/vbot-game/tickets

    NOTE:
        If you are running from the source repository:

        In order to get the program running properly,
        the file robot.svg must be built first.

        In Inkscape, open robotlinks.svg
            data/robot/robotlinks.svg

        Run the "Embed Images" script.
            Extensions -> Images -> Embed Images

        NOTE: IF Embed Images crashes!
            * open 'Edit > XML Editor...'
            * select the node <sodipodi:namedview ...> in the list on the left
            * select the attribute 'id' in the upper right list
            * at the bottom right, the string of the id is shown in the edit field
                (probably something like "namedview12345" - numbers will vary)
            * overwrite the id string with "base", click on 'Set', close XML Editor

        "Save As" robot.svg in the data/robot folder.


        If you do not want to generate the file yourself,
        try downloading the most recent release and copying
        over the robot.svg file from there.


ADDING LEVELS:
    Look at the other levels in the "levels" file to see the format.

    Add your level in the position you want it to appear in the game.
        Set the difficulty value between the values of the levels
            it appears between.

            (levels will be sorted by difficulty in the game)

        The level number (#1, #2, etc) is not checked and will be
            regenerated automatically in the next steps.

    Be sure to leave a blank line between levels, and several blank
        lines at the end of all of the levels.

    Add a solution to your level in the matching place in solutions.py

    Test your level and solution with:
        python3 game.py

    Finally, to rewrite level numbers, run:
        python3 game.py -R
    If you also want to smooth out level difficulties, use:
        python3 game.py -R -S

    levels_NEW and solutions_NEW will be written. Copy those files to
        levels and solutions.py respectively.


REMOTE SCOREKEEPER:
    A simple remote scorekeeping server is provided.
    NOTE: This server should NOT be exposed to the internet!

    The server can be started from the menu Settings -> Score Server...


    OR Start the server with:
        python3 scoreserver.py -I
        to create and initialize the score database

        python3 scoreserver.py
        to have the server start listening for connections from vBot


        Also, use:
        python3 scoreserver.py -U
        to update the database if new levels are added



    To create your own remote scorekeeping server:

    Provide 3 methods available over http.

    levels() should accept a single GET parameter of "name"
    and return a newline separated list of the hashes of
    the levels that person has completed.

    add_level() should accept 2 GET parameters, "name" and
    "lvlhash" and store the hashes of the levels that player
    has completed. Optionally, add_level can take a "points"
    parameter and store the number of points awarded for
    that level.

        If using the "points" parameter, be sure to enable
        send_points in conf.py and look at the get_points
        method in level_points.py

    check_hashes() should accept a list of the hashes for the
    boards being used by vBot (the list should be in the form
    of a single string with '|' used to separate the entries)
    and return 'SUCCESS' if the list matches the hashes known
    to the score server.