# Game Map (H5P.GameMap)

A map with stages, each holding exercises; finishing a stage opens the stages joined to it.

- `gamemapSteps.backgroundImageSettings.backgroundImage` is the map.
- Each item of `gamemapSteps.gamemap.elements` is a stage: a `label`, its exercises under `contentsList` (`[{ "contentType": { "library": "…", "params": { … } } }]`), its `neighbors` named by label, and `telemetry.x` and `telemetry.y`, its place in percent of the map from the top left. The build joins neighbours both ways, sets the ids the map keeps, and spreads out stages written without a place.
- At least one stage has `canBeStartStage: true`.
- `behaviour.lives` and `behaviour.timeLimitGlobal` make it a game; leave them out for a plain path.

## Example

```json
{
  "type": "H5P.GameMap",
  "params": {
    "gamemapSteps": {
      "backgroundImageSettings": { "backgroundImage": { "path": "valley.png" } },
      "gamemap": {
        "elements": [
          {
            "label": "Source",
            "canBeStartStage": true,
            "telemetry": { "x": 15, "y": 20 },
            "neighbors": ["Mouth"],
            "contentsList": [{ "contentType": { "library": "H5P.TrueFalse", "params": { "question": "A river can begin at a glacier.", "correct": "true" } } }]
          },
          {
            "label": "Mouth",
            "telemetry": { "x": 75, "y": 70 },
            "contentsList": [{ "contentType": { "library": "H5P.MultiChoice", "params": { "question": "Where does a river end?", "answers": [{ "text": "In a sea or a lake", "correct": true }, { "text": "In the mountains", "correct": false }] } } }]
          }
        ]
      }
    }
  }
}
```

<!-- Generated by `h5p-author schema --markdown` from the pinned pack. Do not edit by hand. -->

## Fields of H5P.GameMap 1.5

The example is `type` and `params` alone, and `params` holds the fields below. A source also names its own `title`, `language`, `license` and `authors`, all four required: the build refuses a source that leaves out any of them. The author's name and the licence are the user's: ask for what they have not given. For a name they skip, write the one you know them by, or "Unknown"; for a licence they skip, `U`.

- `showTitleScreen` boolean = false — Show title screen
- `titleScreen` group — Title screen
  - `titleScreenIntroduction` html: sub sup strong em code u del a ul ol hr pre code = "<p style=\"text-align: center;\"></p>" — Introduction
  - `titleScreenMedium` sub-content: H5P.Image | H5P.Video — Title screen media
- `headline` text — Headline: Optional headline for the titlebar.
- `gamemapSteps` group — Game map editor
  - `backgroundImageSettings` group — Background
    - `backgroundImage` image file — Background image
    - `backgroundColor` text = "rgb(255, 255, 255)" — Background color: Choose a color to use as the background of the game map.
  - `gamemap` group — Game map
    - `elements` list of — Elements
      - `label` text, required — Stage label: This label will be displayed on top of your exercise and will help you to connect different stages with one another.
      - `canBeStartStage` boolean = false — User can start here
      - `time` group — Time limit
        - `timeLimit` number 1– — Time limit: Optional time limit in seconds. If a user exceeds this time, the exercise will close, be reset, and the user will loose a life if lives are limited.
        - `timeoutWarning` number 1– — Timeout warning time: Optionally set when a timeout warning audio should be played (number of remaining seconds). An audio needs to be set in the audio settings.
      - `accessRestrictions` group — Access restrictions
        - `allOrAnyRestrictionSet` one of "all" | "any" = "all" — All or any restriction set: Choose if all or any of the following restrictions need to be met.
        - `restrictionSetList` list of — Restriction sets
          - `allOrAnyRestriction` one of "all" | "any" = "any" — All or any restriction: Choose if all or any of the following restrictions need to be met.
          - `restrictionList` list of — Restrictions
            - `restrictionType` one of "totalScore" | "stageScore" | "stageProgress" | "time" = "totalScore" — Restriction type
            - `totalScoreGroup` group — Total score
              - `totalScoreOperator` one of "lessThan" | "equalTo" | "notEqualTo" | "greaterThan" = "greaterThan" — Operator for total score
              - `totalScoreValue` number — Value of total score to compare to
            - `stageScoreGroup` group — Stage score
              - `stageScoreId` value — Stage to get score from
              - `stageScoreOperator` one of "lessThan" | "equalTo" | "notEqualTo" | "greaterThan" = "before" — Operator for stage score
              - `stageScoreValue` number — Score score to compare to
            - `stageProgressGroup` group — Stage progress
              - `stageProgressId` value — Stage to get progress from
              - `stageProgressOperator` one of "is" | "isNot" = "is" — Operator for stage progress
              - `stageProgressValue` one of "unstarted" | "opened" | "completed" | "cleared" = "open" — Progress to compare to
            - `timeGroup` group — Time
              - `timeOperator` one of "before" | "is" | "is not" | "after" = "before" — Operator for time
              - `timeValue` text — Time to compare to
      - `contentsList` list 1+ of, required — Contents
        - `contentType` sub-content: H5P.Accordion | H5P.Agamotto | H5P.Audio | H5P.AudioRecorder | H5P.CoursePresentation | H5P.Crossword | H5P.Dialogcards | H5P.DragQuestion | H5P.DragText | H5P.Essay | H5P.Blanks | H5P.ImageHotspotQuestion | H5P.Image | H5P.MultiMediaChoice | H5P.ImageHotspots | H5P.ImageSlider | H5P.InteractiveVideo | H5P.MarkTheWords | H5P.MemoryGame | H5P.MultiChoice | H5P.QuestionSet | H5P.SingleChoiceSet | H5P.AdvancedText | H5P.TrueFalse | H5P.Video, required — Stage content: Choose the type of content you would like to add.
      - `specialStageType` one of "finish" | "extra-life" | "extra-time" | "link", required — Special stage type
      - `specialStageExtraLives` number 1– = 1 — Number of extra lives: Set how many lives the user will get when entering this stage.
      - `specialStageExtraTime` number 1– = 1 — Number of seconds of extra time: Set how many seconds the user will gain for the global time limit when entering this stage.
      - `specialStageLinkURL` text, required — URL to link to: Set where the user should be sent to when opening this stage.
      - `specialStageLinkTarget` one of "_blank" | "_parent" = "_blank" — Place to open link in
      - `alwaysVisible` boolean = false — Always visible
      - `overrideSymbol` boolean = false — Override lock symbol
      - `neighbors` list of values, required — Connected stages
      - `telemetry` group, hidden in the editor — Telemetry
        - `x` text, required
        - `y` text, required
        - `height` text, required
        - `width` text, required
    - `paths` list of — Paths
      - `visualsType` one of "global" | "custom" = "global" — Visual settings
      - `customVisuals` group — Custom visual settings
        - `colorPath` text = "rgba(0, 0, 0, 0.7)" — Color path
        - `pathWidth` one of "0.1" | "0.2" | "0.3" = "0.2" — Path width
        - `pathStyle` one of "solid" | "dotted" | "dashed" | "double" = "dotted" — Path style
- `endScreen` group — End screen
  - `noSuccess` group — User not successful
    - `endScreenTextNoSuccess` html: sub sup strong em code u del a ul ol hr pre code = "<p style=\"text-align: center;\"></p>" — Message (user not successful)
    - `endScreenMediumNoSuccess` sub-content: H5P.Image | H5P.Video — End screen media (user not successful)
  - `success` group — User successful
    - `endScreenTextSuccess` html: sub sup strong em code u del a ul ol hr pre code = "<p style=\"text-align: center;\"></p>" — Message (user successful)
    - `endScreenMediumSuccess` sub-content: H5P.Image | H5P.Video — End screen media (user successful)
  - `overallFeedback` list 1+ of — Overall Feedback: Click the "Add range" button to add as many ranges as you need. Example: 0-20% Bad score, 21-91% Average Score, 91-100% Great Score!
    - `from` whole number 0–100 = 0 — Score Range
    - `to` whole number 0–100 = 100
    - `feedback` text — Feedback for defined score range
- `visual` group — Visual settings
  - `stages` group — Stages
    - `colorStage` text = "rgba(250, 223, 10, 0.7)" — Color not visited stage
    - `colorStageLocked` text = "rgba(153, 0, 0, 0.7)" — Color locked stage
    - `colorStageCleared` text = "rgba(0, 130, 0, 0.7)" — Color cleared stage
    - `showScoreStars` one of "never" | "onHover" | "always" = "never" — Show stars for scores: Choose if and when stars will be displayed on the map for the scores of the stages. Please note that stages without scored exercises will not get the stars.
  - `paths` group — Paths
    - `displayPaths` boolean = true — Display paths
    - `style` group — Style
      - `colorPath` text = "rgba(0, 0, 0, 0.7)" — Color path
      - `colorPathCleared` text = "rgba(0, 130, 0, 0.7)" — Color path cleared
      - `pathWidth` one of "0.1" | "0.2" | "0.3" = "0.2" — Path width
      - `pathStyle` one of "solid" | "dotted" | "dashed" | "double" = "dotted" — Path style
  - `misc` group — Miscellaneous
    - `useAnimation` boolean = true — Animate map
- `audio` group — Audio settings
  - `backgroundMusic` group — Background music
    - `music` audio files — Background music
    - `muteDuringExercise` boolean = true — Mute when taking exercises
  - `ambient` group — Events
    - `clickStageLocked` audio files — Click on locked stage
    - `checkExerciseNotFullScore` audio files — Check exercise (not full score)
    - `checkExerciseFullScore` audio files — Check exercise (full score)
    - `unlockStage` audio files — Unlocking a stage
    - `openExercise` audio files — Open exercise
    - `closeExercise` audio files — Close exercise
    - `showDialog` audio files — Show dialog
    - `fullScore` audio files — Full score
    - `lostLife` audio files — Lost a life
    - `gainedLife` audio files — Gained life
    - `gameOver` audio files — Game over
    - `extraTime` audio files — Gained extra time
    - `timeoutWarning` audio files — Timeout warning
    - `endscreenNoSuccess` audio files — End screen (not full score)
    - `endscreenSuccess` audio files — End screen (full score)
- `behaviour` group — Behavioural settings
  - `lives` whole number 1– — Lives: Set the number of lives for a user or leave empty for unlimited lives. Users will lose a life when they do not get full score and they cannot continue once all lives are lost.
  - `timeLimitGlobal` whole number 1– — Global time limit: Optional time limit in seconds for the whole game. If a user exceeds this time, the game will be over immediately.
  - `timeoutWarningGlobal` whole number 1– — Timeout warning time: Optionally set when a timeout warning audio should be played (number of remaining seconds). An audio needs to be set in the audio settings.
  - `finishScore` whole number 0– — Finish score: Optional score that can be lower than the summed maximum score of all exercises, so users can receive full score without completing all exercises.
  - `enableRetry` boolean = true — Enable "Retry" button
  - `enableSolutionsButton` boolean = true — Enable "Show solutions" button
  - `map` group — Map
    - `showLabels` boolean = true — Show stage labels
    - `roaming` one of "free" | "complete" | "success" = "free" — Roaming: Choose whether users can roam all stages freely, need to finish a stage to get access to that stage's neighbors, or need to pass a stage to get access to that stage's neigbors.
    - `fog` one of "all" | "1" | "0" = "all" — Visibility range: Select how far the user can see ahead

75 interface texts are left out: they come from the libraries' translations. `h5p-author schema H5P.GameMap --all` lists them, for a source to set one.

<!-- End of the generated section. -->