Skeletons

This article goes through how to use the skeleton classes to write implementations. This is the preferred way of creating new exercises, challenges, etc.

The article contains both a broad overview of the material as well as deep dives, it is recommended to start reading the broad sections and come back to the sub-sections as questions arise.

Why and how to use

The skeletons are base classes that handles things that most implementations will need or things that are required. The specialized skeletons also provides a bunch of functionality that otherwise would take a lot of work to implement.

The provided skeletons form a hierarchy where the children inherit functionality from the parent skeletons:

BasicChallenge - Provides the most common functionality
- StageChallenge - Provides a GUI structure and a couple other features
  - GameChallenge - Provides a bunch of features realated to making a turn-based game

To use a skeleton the Challenge class should inherit from the skeleton class. Each skeleton has a number of required methods that need to be implemented. We provide a basic template for each skeleton under respective heading, which are good starting points for creating a challange.

`BasicChallenge`

This is the base of all the skeletons and provide the essential functionality, which will be used by all other skeletons as well. However, keep in mind that some skeletons do implement some of the BasicChallenge methods for you.

Template for BasicChallenge:

"""
This is the module containing the challenge implementation.
"""
from lib.exceptions import SolutionException
from lib.skeletons import BasicChallenge, LevelInfo
from lib.ui import Rectangle, Text


class Challenge(BasicChallenge):
    """
    This is a challenge implementation using the basic skeleton.
    """

    def setup_level(self, level):
        """
        This method returns required level information for the current level.
        The `level` parameter is the level index, starting at 0.
        """
        return LevelInfo(name=f"Level {level + 1}", max_score=10)

    def setup_state(self):
        """
        This method is where you should do all initial setup, except for graphics.
        """
        # For example, setting up a variable which can be used later on
        self.my_variable = 5
        # Or writing a message in the console
        self.console.log("Hi console!")

    def setup_canvas(self):
        """
        This method is where you should create the initial graphics.
        """
        # For example, creating a square
        self.my_square = Rectangle(w=20, h=20, x=20, y=20, color="green", parent=self.canvas)
        # And putting text inside it
        self.my_text = Text("N", font_size=10, color="white", parent=self.my_square)

    def update_state(self):
        """
        This method is where you should call solutions and update the current state.
        It is called continuously until `self.finished` is set to `True`.
        """
        # When calling a solution you need to handle any `SolutionException`
        try:
            solution = self.context.solutions[0]
            # TODO: call a solution method
        except SolutionException:
            # Code put here will run if the solution crashed
            pass

        # This is a good place to update the scores
        self.scores[0] = self.my_variable

        # You will want to set this conditionally if your challenge involves multiple steps
        self.finished = True

    def update_canvas(self):
        """
        This method is where you should update the graphics based on the current state.
        """
        # For example, changing the text inside the square
        self.my_text.text = str(self.my_variable)

Required methods

setup_level(self, level)

Must return a LevelInfo object which includes the information needed for the framework to handle the level.

The level parameter is the index of the current level, starting at 0.

The LevelInfo object has the following attributes:

name - The name of the level
max_score - The maximum possible score for a solution
show_canvas - Whether the level uses the canvas, defaults to True

setup_state(self): Setup the challenge state here.; Will be called once at startup, after setup_level.
setup_canvas(self): Setup the canvas here.; Will be called once at startup, after setup_state, unless show_canvas is False.; Note that this method is implemented by most of the other skeletons, so do not add your own when using those.
update_state(self): Call solutions and update the challenge state here.; When calling solutions you must catch any SolutionExceptions that are raised.; Will continuously be called until self.finished is set to True, so remember to do that.; Note that once that happens no other method is called, so remember to also update the scores.
update_canvas(self): Make any changes to the canvas here.; Will be called immediately after update_state, unless show_canvas is False.; Note that this method is implemented by most of the other skeletons, so do not add your own when using those.

Features

The main feature of this skeleton is reduced boilerplate and some minor conveniences. Here is a list of class members and what they are used for:

finished: A boolean that should be set to True when the challenge has ended.
scores: A list of scores for each solution, indices match the solution indices.; Scores start at 0 and must be updated manually.
canvas: Represents the canvas itself and is the top of the graphical hierarchy.
console: Represents the console, and can be used to log messages.
context: Used to access various features, but most commonly used to access solutions.
session: Used for interact mode, see subsection.
settings: Used for interact mode, see subsection.

Interact Mode

Interact mode is an advanced feature that is used to make challenges with interactive canvases. This skeleton has a couple of conveniences related to interact mode.

TODO: finish section