Getting Started

Starter Guide for Legends of Learni

Initializing Legends of Learning API in Construct 3

A typical layout flow for a game at LoL made in Construct 3 should look similar to this.

It’s strongly recommended to use a Game Loader layout. By this, I don’t refer to the Construct 3 loader layout, but to a game layout intended to load local resources and complete initializations before even showing the title screen. However, the game loader and the title screen responsibilities could be combined in a single layout. It's up to you to decide.

This workflow ensures that all your resources are loaded and the LoL API is initialized correctly before showing the title screen.

Step 1: Install the LoL API Plugin

Before you can start using the Legends of Learning API, you first need to install the LoL Plugin in Construct 3:

Open Construct 3.
Go to the Plugins section by navigating to View > Addon Manager in the menu bar.

Search for the LoL API Plugin and install it.

Once installed, you will see the LoL API object available in your project.

Step 2: Create the Project in Construct 3

Open Construct 3 and create a new project.
Choose an appropriate game resolution (ensure that it follows Legends of Learning’s required resolution of 1024x576, which has a 16:9 aspect ratio).
- Go to the Layout Properties and set the Viewport Size to 1024x576.

This resolution ensures your game will scale correctly on all devices that Legends of Learning supports. You can use different resolution sizes, as long as the aspect ratio remains 16:9. However, keep in mind the chromebooks used at schools have fewer graph capabilities. Keep it a the minimum necessary for better performance (recommended 854x480).

Step 3: Call `Game Is Ready`

Before interacting with any other LoL API functions, you must first initialize the game to let Legends of Learning know that your game is ready to communicate. The Game Is Ready action should be called first in the event sheet.

Action Example: Game Is Ready
- In your event sheet, add the following action after finishing loading all your game resources:

Game Is Ready should be called just once per game loaded.

Explanation:
- Game Is Ready informs the Legends of Learning platform that your game is set up and ready to start receiving and sending data, such as progress, questions, and answers.
- This action is critical as no other LoL-related API calls should be made before calling Game Is Ready.
- Game Is Ready is usually called from the Loader layout, even before showing the title screen.

Step 4: Respond to `On Start`

Once Game Is Ready is triggered, your game should respond to the On Start condition. This condition is triggered when Legends of Learning signals that your game is now live and can interact with the platform.

Condition Example: On Start

Explanation:
- On Start should be used to initialize the game’s starting state, such as setting up the score, initializing level progress, or displaying a welcome message to the player.
- On Start Receives the language file from LoL's backend, containing the language set by the teachers for the game. See Step 7: Understanding the lang.json File Structure
- This is the point where you prepare any game data that needs to be shown or tracked when the game starts.

Step 5: Call `Load State`

Once your game has started, you need to allow the player to continue from where they left off, if applicable. The Load State action retrieves the saved game state from Legends of Learning, so the player can resume where they stopped. As shown in the previous step, it is usual to call Load State after LoL confirmed the game can start.

Explanation:
- Load State loads the saved data (e.g., score, level) that was previously stored in the Legends of Learning backend.
- You can call Load State at the beginning of the game after On Start to restore the player’s previous progress.

Step 6: Respond to `On Load State`

After calling Load State, the On Load State condition is triggered when the game successfully loads the saved state.

Condition Example: On Load State

Explanation:
- On Load State triggers once the saved data (e.g., score, progress) is retrieved from Legends of Learning.
- This is useful for updating the game state to reflect the player’s previous session and displaying that information.
Example Save State Data:
```
{
  "score": 1000,
  "level": 5,
  "max-combo":3
}
```

Step 7: Understanding the `lang.json` File Structure

The lang.json file is crucial for managing the text content in your game. Legends of Learning automatically translates the text based on the player’s language. You need to structure the file correctly to ensure smooth localization.

Basic Structure:

The lang.json file contains translations of text keys. The keys are the identifiers for text strings used in your game, and the values are the corresponding translations.

Example of a valid lang.json file:

{
  "en": {
    "ui-play": "Play the game",
    "ui-pause": "Pause",
    "level-complete": "Level Complete"
  },
  "es": {
    "ui-play": "Jugar al juego",
    "ui-pause": "Pausa",
    "level-complete": "Nivel Completado"
  }
}

Explanation:
- "en": Contains the English text for your game.
- "es": Contains the Spanish translation.
- Each key (e.g., "ui-play") corresponds to a piece of text in the game.
- You only need to provide the English version. Legends of Learning will handle the translations for other languages automatically.
Important Notes:
- Ensure that all the keys in your lang.json file are correctly named and match the text IDs in your game.
- Don’t include language blocks with incomplete translations. This will cause errors when uploading the lang.json file.
- Make sure that special characters (like accents in Spanish) render correctly in your game’s UI.