BamBirds 2022

• BamBirds 2022
  • [Team Description](doc/Team Descriptions/team_description_2022.md)
  • Repository structure
  • Prerequisities
    • Using AngryBirds (via Chromium)
    • Using ScienceBirds
  • Run from distribution
  • Run from source
    • With AngryBirds
      • With Docker
    • With ScienceBirds
    • Using Gradle
    • Configuration
    • Python execution
    • Troubleshooting
    • Debugging

Warning: Some of the setup described here is specific to the way the project is setup internally. Some of the things like the angry birds server or our setup of the ABServer cannot be provided publicly because of legal constraints.

If you want to contribute / collaborate with us, please contact Diedrich Wolter

[Team Description](doc/Team Descriptions/team_description_2022.md)

Repository structure

BamBirds is a gradle project and contains the following modules:

• common/: Common Utils and Data Structures
• client/: Client for connecting to ABServer or SBServer
• vision/: Vision recognition for AngryBirds and ScienceBirds
• planner/: Action planner (More info in the README)
  • src/main/prolog: Prolog Planner
  • src/main/java: Knowledge generation and plan parsing for Prolog
  • behind_the_corner: SWI-Prolog native library for rebounds
• level_selection/: Module for the Level Selection, containing Models for Prediction of Score and Level Outcome
  • src/main/java: The module for executing models in the agent
  • src/main/python: Python Module for generating Models for Java
  • src/main/csharp: C# Module for generating a Dirichlet Model
• debugging/: WIP shell for debugging and manual interaction with the modules
• src/: Bambirds Agent
  • main/java: Java Code for the agent
  • main/python: Python code for automated execution of the agent

Additional Resources and Information can be found here:

• doc/: documentation, project reports etc.
• game/: files required to install and start the AngryBirds Game (including instructions in README file), custom levels (with chrome extension), level editor

Prerequisities

• Install Java >= 8, <= 17 (Optimally >= 12 so the same jdk can be used for ScienceBirds)
• Install SWI-Prolog >= 8.2.4
  • Make sure to set PATH_TO_SWIPL in config.properties to the executable on the system if is not located on the PATH (System Variables on Windows)
• A c++ compiler for native prolog libraries
  • Windows:
    • To get it fully working use wsl and follow linux instructions
    • Otherwise the native prolog libraries will not be included (would be used for advanced rebound calculations)
  • Linux, MacOS, WSL:
    • G++ compiler with support for C++11 (gcc, clang)
    • libboost-dev (Boost C++ development libraries)
• (Optional) Python >= 3.8 for some modules and evaluation

Or if you want to run with docker:

• docker
• docker-compose

Using AngryBirds (via Chromium)

• Setup AngryBirds and ABServer according to game/README.md

Using ScienceBirds

• Clone the ScienceBirds Framework
  • Install a Java 12 or higher
  • Extract the ScienceBirds Game in ScienceBirds folder

Run from distribution

The distribution contains a bin and a lib folder.

To run the agent, run the command

./bin/bambirds

Configuration can be done either with the config/config.properties file or with commandline options.

For more information run

./bin/bambirds --help

Run from source

Make sure you are in the root directory of the BamBird repository (the same directory this very file is located in).

With AngryBirds

1. Open this url in Chromium: chrome.angrybirds.com

   Make sure System is correctly configured. You have to select SD mode of the Angry Birds game, otherwise the Agent won't work.

2. Run the AIBirds server:

   Open a terminal and enter the following command:

   ./gradlew game:abserver:run

   This will open the server application.

3. Run the Agent:

   Open another terminal and enter this command:

   ./gradlew :run

   Now the server application should have detected a connected client. Press Start in the server application.

   Make sure to set SERVER_TYPE=ANGRY_BIRDS in the configuration

4. Shutdown:

   Server: simply close the server application window or open the terminal in which you started the server and press Ctrl-C.

   Agent: open the terminal in which you started the agent and press Ctrl-C.

With Docker

You can simplify the approach with docker. By default the docker-compose.yml file only contains the game and connection server.

docker-compose up -d

Then open the URL in Chromium chrome.angrybirds.com. Make sure System is correctly configured (Running the game is already done with the previous command)

To run the agent in docker as well, you can create a docker-compose.override.yml with the following content:

services:
  agent:
    image: registry.sme.uni-bamberg.de/bambirds/testing/build
    working_dir: /bambirds
    # If your user id is not 1000, change it to your userid (`id -u` on linux)
    #
    # It is not required, but highly advised to set this, since then all generated gradle files are not
    # created with the wrong permissions
    user: "1000"
    volumes:
      - ./:/bambirds
    command:
      - ./gradlew 
      - :run
      - --args=-h abserver

Then start this container with

docker-compose up -d agent

If you want to execute other commands inside the agent, replace the command with your command or the following:

    command:
      - sh
      - -c
      - while :; do sleep 2073600; done

Then use this to execute a command inside the container (bash for normal shell):

docker-compose exec agent <your command>

Important is here, that this will most of the time not work on native windows because of the nasty \r and the different filesystem. If you want to run on windows, you are better off cloning the project in wsl.

With ScienceBirds

1. Start the ScienceBirds Unity Game

2. Run the AIBirds server:

   Open the folder sciencebirdsframework and use java 12 or higher to run. For example:

   /usr/lib/jvm/java-13-openjdk/bin/java -jar game_playing_interface.jar

   This will start the server application.

3. Run the Agent:

   Open another terminal and enter this command:

   ./gradlew :run

   Make sure to set SERVER_TYPE=SCIENCE_BIRDS in the configuration

4. Shutdown:

   Server: open the terminal in which you started the server and press Ctrl-C.

   Agent: open the terminal in which you started the agent and press Ctrl-C.

Using Gradle

The BamBird agent can be compiled, run and packaged using Gradle.

Use one of the following tasks:

• tasks

  Display all available Tasks

• game:abserver:run

  Execute the AIBirds server (game/abserver).

• :run

  Execute the BamBird agent (de.uniba.sme.bambirds.BamBirds).

  Configuration should be done via the config/config.properties file.

  For testing purposes the default values should be just fine.

  The : before run is required to only run the root project and not other projects with the application plugin

• test

  Run JUnit tests

• distTar/distZip

  Create a tar/zip containing executables, all dependencies and Prolog files in the build/distributions/ directory. Files in src/main/dist will be included.

• compileJava

  Compile all Java files

• clean

  Remove the build/ directory.

• javadoc

  Generate the javadoc in build/docs/javadoc directory

• <subproject>:<task> Execute a Task for a subproject

Configuration

All configuration is saved in config/config.properties (file is created on the first execution of the agent):

Name	Options/Type	Use	Access in source
HOST	any server domain or ip	the location of ABServer or SBServer	Settings.SERVER_HOST
GAME_MODE	COMPETITION | TRAINING | DEMO	can be used for changing mode of Agent between competition or training. The demo mode enables the visual export of the generated plans and display in Java (requires pdflatex and convert, for windows install ImageMagick and GhostScript).	Settings.GAME_MODE
ROUNDS	int value	when level-selection disabled the number of complete rounds to play, -1 for unlimited	Settings.ROUNDS
TEAM_ID	uint value	The id used to connect to server	Settings.TEAM_ID
SERVER_TYPE	ANGRY_BIRDS | SCIENCE_BIRDS	Switch between the ABServer and SBServer (they have slightly different APIs)	Settings.SERVER_TYPE
START_LEVEL	int value	The id of the first level to play	Settings.START_LEVEL
PATH_TO_SWIPL	file path or command	The location of the swipl executable (On windows for example "C:\\Program Files\\swipl\\bin\\swipl")	Settings.PATH_TO_SWIPL
LEVEL_RANGE	int value	The range of levels to play, 0 for all available, 1 for only the START_LEVEL	Settings.START_LEVEL
VISUAL_DEBUG_ENABLED	boolean value	Enable Visual Debugging	Settings.VISUAL_DEBUG_ENABLED
EXPORT_LEVEL_STATS	boolean value	Export level statistics	Settings.EXPORT_LEVEL_STATS
DISABLE_LEVEL_SELECTION	boolean value	Disable the level seletction completely and run levels iterative	Settings.DISABLE_LEVEL_SELECTION
LEVEL_SELECTION_FIRST_ROUND_ITERATIVE	boolean value	Run the first round of levels iterative	Settings.LEVEL_SELECTION_FIRST_ROUND_ITERATIVE

Optionally also cli arguments can be passed to gradle with

./gradlew run --args='--help'

Python execution

Some modules and scripts are written in python. The entrypoint is main.py where the entrypoints for the modules are reqistered.

Before execution you need to install some dependencies:

pip install -r requirements.txt

Then run main.py to see all registered modules:

python main.py --help

Troubleshooting

• Verify that Gradle picks the correct Java version by running ./gradlew --version.
• Verify that you have the correct Chromium version
• Verify that you can execute swi-prolog from the command line: swipl (or the path you have set in config.properties)
• (DEMO Mode on windows) Verify that you have both ImageMagick and GhostScript installed and available from the command line. Try magick.exe situation1-1.pdf situation1-1.jpg

Debugging

The Debugging can be done also via gradle with an external debugger like in eclipse, intellij or vscode (with the "Debugger for Java" extension)

Run the jvm in debugging mode with

./gradlew :run --debug-jvm

and then attach to it on Port 5005. For VSCode the debugging task "Debug (Attach) - Local" will do exactly that.