Educational Game Format (EGF) 1.1 Specification

Home page/Specifications/Specification 1.1

§ 1. Introduction

The Educational Game Format (EGF) is an open file format designed to provide a simple and portable standard to represent, package, and play educational games. The objectives of EGF are to make educational games easier for educators to author and easier for learners to access worldwide. The format is explicitly designed for interoperability: any EGF-compliant Editor MUST produce EGF Packages that can be correctly opened and played by any EGF-compliant Reader that supports the features used in those files. EGF Readers and EGF Editors MAY be implemented as Android applications, iOS applications, web applications, or other types of software.

Copyright © 2025 EGF Project Authors. All rights reserved.

The EGF 1.1 Specification and all related documentation are protected under copyright law. No part of these materials may be reproduced, distributed, or modified without the prior written permission of the authors, except as expressly permitted under the EGF Specification License 1.0.

The authors' moral rights are asserted and protected.

The EGF 1.1 Specification is released under the EGF Specification License 1.0.

§ 3. Normative language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

§ 4. Core Concepts and Terminology

At the heart of EGF is the EGF Sequence. The EGF Sequence is composed of Scenes. By default, Scenes are presented in the order in which they appear in the EGF Sequence, forming the baseline flow of the EGF Game. Certain Roles MAY define navigation actions that temporarily deviate from this order, as described in Section 11.

All href and full-path values in an EGF Package MUST use relative paths rather than absolute ones.

The value of any full-path attribute (such as the full-path attribute of the META-INF/container.xml <rootfile> element) MUST be expressed relative to the root of the ZIP archive.

The value of any href attribute in the EGF Core File or in any other XML resource (for example, a game_title.xml or mcq_simple_01.xml file) MUST be expressed relative to the location of the file in which that attribute appears.

All text-based resources in an EGF Package MUST be encoded in UTF-8. This includes the EGF Core File, all referenced XML resources, and any text/plain resources. An EGF Reader MUST decode these resources as UTF-8.

EGF Package

A ZIP archive identified as an Educational Game Format package by the presence of an EGF container and an EGF Core File. An EGF Package MAY be invalid or non-conforming, conformance to a specific EGF version is defined in Section 12.

EGF Game

The logical game experience represented by a single EGF Package. An EGF Game is defined by its EGF Core File, its resources, and the behavior implied by the types of its Scenes.

EGF Core File

The XML file referenced from META-INF/container.xml as the rootfile. This file MUST have an <egf> root element and defines the metadata, manifest, sequence, and settings of the EGF Game.

EGF Reader

A software component (for example, a native app or web application) that is able to open, validate, and render an EGF Package according to this Specification.

EGF Editor

A software component that is able to create or modify an EGF Package and produce EGF Packages that conform to this Specification.

EGF Manifest

The <manifest> element in the EGF Core File. The manifest is a registry of all resources that can be referenced by the EGF Game.

Manifest Item

An <item> element inside <manifest>. Each Manifest Item MUST have at least id and role attributes and identifies a single resource within the EGF Package. Additional attributes (such as href, media-type, or value) MAY be required depending on the value of the role attribute, as defined in Section 9.

Role

The semantic type assigned through the role attribute. A Role is used both in the EGF Manifest (for Manifest Items such as game_title_simple, mcq_simple, or video_simple) and inside Scene XML files (for local items such as game_title_image or good_answer_audio), as defined in Section 9. The Role determines how an EGF Reader MUST interpret and render the resource referenced by that item.

Core Role

A Core Role is any Role whose semantics are defined normatively in Section 9.1 of this Specification. Core Roles are predefined by the EGF Specification and MUST be interpreted exactly as defined in those sections.

Custom Role

A Custom Role is any role name that is not a Core Role and that starts with the prefix "x-". Custom Roles are defined in Section 9.2 and MAY be used only in EGF 1.1 Extended Packages, as described in Section 9.2.

Valid Role

A Valid Role is any role name that is either a Core Role or a Custom Role (as defined above). All Conforming EGF 1.1 Packages use only Core Roles. Custom Roles are allowed only in EGF 1.1 Extended Packages as defined in Sections 9.2 and 12.1.

Scene

A logical unit of content that can be presented by an EGF Reader as part of the game flow. In this Specification, a Scene is any Manifest Item that is referenced from the <sequence> element by its id.

Special Scene

A Scene whose Role has additional constraints on its position in the Sequence or its behavior (for example, game_title_simple, congratulations_simple, and other roles defined in Section 9).

Game Title Scene

In EGF 1.1, the Game Title Scene is the unique Scene whose Manifest Item has the role game_title_simple.

Congratulations Scene

In EGF 1.1, the Congratulations Scene is the unique Scene whose Manifest Item has the role congratulations_simple.

Game Over Scene

In EGF 1.1, the Game Over Scene is the unique Scene whose Manifest Item has the role game_over_simple.

Credits Scene

In EGF 1.1, the Credits Scene is the unique Scene whose Manifest Item has the role credits_simple.

EGF Sequence

The <sequence> element in the EGF Core File. The EGF Sequence is an ordered list of <scene> references that defines the order in which Scenes are presented by the EGF Reader.

EGF Settings

The <settings> element in the EGF Core File. The EGF Settings define game-level configuration values that an EGF Reader MUST use to adjust the behavior of the EGF Game.

Setting

A <setting> element inside <settings>. Each Setting MUST have a ref attribute whose value is the id of a Manifest Item defined in the EGF Manifest. The Role of that referenced Manifest Item determines the game-level configuration value that an EGF Reader MUST use to adjust the behavior of the EGF Game.

Gameplay Session

A Gameplay Session is a single run of the EGF Game. It begins when the learner activates the control to start the game from the Game Title Scene and the first non-Game Title Scene in the EGF Sequence becomes active, and ends just before the learner reaches either the Congratulations Scene or the Game Over Scene, or exits the game. A Gameplay Session corresponds to all Scenes placed in the EGF Sequence after the Game Title Scene and before the Congratulations Scene.

§ 5. General structure

An EGF Package is a ZIP archive with this structure:

mimetype
META-INF/
    container.xml
egf/
    egf.xml
    {files and directories specific to the content}

The file "mimetype" MUST be in mode "STORED", placed first in the ZIP archive, and not compressed. Other files and folders MAY be stored using STORED mode (uncompressed) or the DEFLATE mode with any compression level.

The file "mimetype" MUST contain only this exact string: application/egf+zip.

§ 6. Structure of the file "META-INF/container.xml"

The file "META-INF/container.xml" MUST be a valid XML document whose root element is <container> with a version="1.0" attribute.

The <container> element MUST contain exactly one <rootfiles> child element.

The <rootfiles> element MUST contain exactly one <rootfile> child element.

The <rootfile> element MUST have the following attributes:

Non-normative example:

<?xml version="1.0" encoding="UTF-8"?>
<container version="1.0">
  <rootfiles>
    <rootfile full-path="egf/egf.xml" id="main"/>
  </rootfiles>
</container>

§ 7. Recommended structure for the content of the EGF

While you are free to put the actual content of the EGF where you want in the archive, it is RECOMMENDED to place the content in a folder named "egf" (in lowercase) located at the root of the archive. This way, you can avoid potential compatibility issues across different operating systems that are not case-sensitive, and you will immediately recognize that the ZIP archive is an EGF Package.

§ 8. Structure of the EGF Core File

Non-normative example of an EGF Core File:

<?xml version="1.0" encoding="UTF-8"?>
<egf version="1.1">
  <metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/">
    <dc:identifier id="game_id">urn:isbn:9781234567890</dc:identifier>
    <dc:title>Example Game Title</dc:title>
    <dc:creator id="creator01">John Doe</dc:creator>
    <dc:date>2025-11-11</dc:date>
    <dc:language>en</dc:language>
    <meta property="dcterms:modified">2025-11-12T10:00:00Z</meta>
  </metadata>

  <manifest>
    <item role="egf_cover" href="assets/images/egf_cover.jpg" media-type="image/jpeg" id="egf_cover" />

    <item role="game_title_simple" href="game_title.xml" media-type="application/xml" id="game_title" />
    <item role="video_simple" href="assets/videos/video_simple_01.mp4" media-type="video/mp4" enable-next-button-at-start="false" id="video_simple_01" />
    <item role="video_simple" href="assets/videos/video_simple_02.mp4" media-type="video/mp4" enable-next-button-at-start="true" id="video_simple_02" />
    <item role="mcq_simple" href="mcq_simple_01.xml" media-type="application/xml" id="mcq_simple_01" />
    <item role="image_simple" href="assets/images/image_simple_01.jpg" media-type="image/jpeg" id="image_simple_01" />
    <item role="question_simple" href="question_simple_01.xml" media-type="application/xml" id="question_simple_01" />
    <item role="audio_simple" href="assets/audios/audio_simple_01.mp3" media-type="audio/mpeg" enable-next-button-at-start="true" id="audio_simple_01" />
    <item role="hangman_simple" href="hangman_simple_01.xml" media-type="application/xml" id="hangman_simple_01" />
    <item role="true_or_false_simple" href="true_or_false_simple_01.xml" media-type="application/xml" id="true_or_false_simple_01" />

    <item role="congratulations_simple" href="congratulations.xml" media-type="application/xml" id="congratulations" />
    <item role="game_over_simple" href="game_over.xml" media-type="application/xml" id="game_over" />
    <item role="credits_simple" href="credits.xml" media-type="application/xml" id="credits" />

    <item role="max_wrong_answers" value="5" id="max_wrong_answers" />
    <item role="background_audio" href="assets/audios/background_audio_01.mp3" media-type="audio/mpeg" scope-from="video_simple_01" scope-to="hangman_simple_01" id="background_audio_01" />
    <item role="foreground_audio" href="assets/audios/foreground_audio_01.mp3" media-type="audio/mpeg" scene-ref="image_simple_01" id="foreground_audio_01" />
  </manifest>

  <sequence>
    <scene ref="game_title" />
    <scene ref="video_simple_01" />
    <scene ref="mcq_simple_01" />
    <scene ref="image_simple_01" />
    <scene ref="question_simple_01" />
    <scene ref="video_simple_02" />
    <scene ref="hangman_simple_01" />
    <scene ref="audio_simple_01" />
    <scene ref="true_or_false_simple_01" />

    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
  </sequence>

  <settings>
    <setting ref="max_wrong_answers" />
    <setting ref="background_audio_01" />
    <setting ref="foreground_audio_01" />
  </settings>
</egf>

In the example above, the assets/ folder is assumed to be a subdirectory of egf/ (egf/assets/). Because href values are relative to the file in which they appear, href="assets/..." in egf/egf.xml refers to egf/assets/... in the ZIP archive.

§ 8.1. Root element named <egf>

The EGF Core File MUST have a root element named <egf> with a version attribute. For EGF 1.1, the value of this attribute MUST be "1.1". This attribute specifies the version of the EGF specification used by the EGF Game.

§ 8.2. Child element named <metadata>

The EGF Core File MUST have an element named <metadata> placed inside the <egf> element with the attribute xmlns:dc="http://purl.org/dc/elements/1.1/" and the attribute xmlns:dcterms="http://purl.org/dc/terms/".

The <metadata> element MUST include the following elements from the Dublin Core Metadata Element Set, Version 1.1:

<dc:title> a required element that MUST contain the title of the EGF Game.

<dc:language> a required element that MUST contain the language of the EGF Game.

Other elements from the Dublin Core Metadata Element Set 1.1, such as those listed below, are allowed and recommended but not mandatory: <dc:creator>, <dc:subject>, <dc:description>, <dc:publisher>, <dc:contributor>, <dc:identifier>, <dc:date>, <dc:type>, <dc:format>, <dc:source>, <dc:relation>, <dc:coverage>, <dc:rights>.

In addition to the mandatory Dublin Core elements listed above, the <metadata> section MUST include a <meta> element with the attribute property="dcterms:modified". This field MUST contain the date and time of the last modification of the EGF Package as an xsd:dateTime value in Coordinated Universal Time (UTC).

Example:

<meta property="dcterms:modified">2025-11-12T10:00:00Z</meta>

§ 8.3. Child element named <manifest>

The EGF Core File MUST have an element named <manifest> placed inside the <egf> element. This element is the EGF Manifest.

All child elements of the EGF Manifest MUST be <item> elements with mandatory id and role attributes. Depending on the value of the role attribute, additional attributes MAY be present.

Each <item> element in <manifest> MUST have an id attribute whose value MUST be unique within the EGF Manifest (that is, no other <item> element in the manifest MUST use the same id value).

All child elements of the EGF Manifest MUST have a role attribute whose value is a Core Role, unless the Package is an EGF 1.1 Extended Package as described in Section 9.2.

The EGF Manifest MUST include Manifest Items for exactly one Game Title Scene, exactly one Congratulations Scene, exactly one Game Over Scene, and exactly one Credits Scene.

§ 8.4. Child element named <sequence>

The EGF Core File MUST have an element named <sequence> placed inside the <egf> element. This element is the EGF Sequence.

All child elements of the EGF Sequence MUST be <scene> elements with a mandatory ref attribute, whose value MUST be the id of an item defined in the EGF Manifest.

In an EGF Core File, each value of the ref attribute used in <scene> elements within the <sequence> MUST be unique within that sequence. In other words, the same Manifest Item id MUST NOT be referenced more than once in the <sequence> element.

If an author wishes to present the same logical content more than once in the game flow, the author MUST declare multiple distinct Manifest Items, each with a different id, and reference each of them at most once in the <sequence>.

These Manifest Items MAY:

provided that each Manifest Item has a unique id.

Non-normative note: This rule ensures that each <scene> element in the EGF Sequence references a unique Manifest Item id, while still allowing authors to repeat gameplay experiences by duplicating Scene definitions. This also avoids ambiguity for EGF Readers that associate runtime state or progress with Scene identifiers.

The EGF Sequence defines the order in which Scenes are displayed. By default, the EGF Sequence is played in the order in which the <scene> elements are written. For example:

<sequence>
    <scene ref="video_simple_01" />
    <scene ref="mcq_simple_01" />
</sequence>

In this example, the EGF Reader MUST first play the Scene with id "video_simple_01", then the Scene with id "mcq_simple_01".

§ 8.5. Child element named <settings>

The EGF Core File MUST have an element named <settings> placed inside the <egf> element. This element is the EGF Settings.

All child elements of the EGF Settings MUST be <setting> elements with a mandatory ref attribute, whose value MUST be the id of an item defined in the EGF Manifest.

An EGF Core File that conforms to this Specification MUST contain exactly one Manifest Item whose role is max_wrong_answers, and the EGF Settings MUST contain exactly one <setting> element whose ref attribute is set to the id of that Manifest Item.

§ 9. Valid roles

In all roles defined in this section, any href attribute MUST follow the rules for relative paths defined in Section 4.

§ 9.1. Core roles

§ 9.1.1 Normal roles

§ 9.1.1.1 text_simple

text_simple is a role designed to render a Scene that presents a single text resource as its primary content. When rendering a text_simple Scene, an EGF Reader MUST display the associated text resource and MUST display a button (or functionally equivalent navigation control) that allows the learner to proceed to the next Scene in the EGF Sequence.

An EGF Reader MAY provide standard text viewing controls (such as font size adjustment, line spacing, and high-contrast mode) when rendering a text_simple Scene. The presence or absence of such controls does not affect conformance to this Specification.

Non-normative note: In typical implementations, the navigation control used to proceed to the next Scene is a button displayed below the text.

Non-normative note: A text_simple Scene is intended to deliver lessons using a text resource. It can be used, for example, to present short reading passages, learning objectives, or hints that the learner reads before continuing.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="text_simple" href="assets/texts/text_simple_01.txt" media-type="text/plain" id="text_simple_01" />
</manifest>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="text_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The item with the role text_simple:

A text_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.1.2. image_simple

image_simple is a role designed to render a Scene that presents a single image resource as its primary content. When rendering an image_simple Scene, an EGF Reader MUST display the associated image resource and MUST display a button (or functionally equivalent navigation control) that allows the learner to proceed to the next Scene in the EGF Sequence.

An EGF Reader MAY provide standard image viewing controls (such as zoom, pan, and full-screen) when rendering an image_simple Scene. The presence or absence of such controls does not affect conformance to this Specification.

Non-normative note: In typical implementations, the navigation control used to proceed to the next Scene is a button displayed below the image.

Non-normative note: An image_simple Scene is intended to deliver lessons using an image resource. It can be used for learners to guess which object, person, or location is shown in a Scene.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="image_simple" href="assets/images/image_simple_01.jpg" media-type="image/jpeg" id="image_simple_01" />
</manifest>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="image_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The item with the role image_simple:

An image_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.1.3. video_simple

video_simple is a role designed to render a Scene that presents a single video resource as its primary content. When rendering a video_simple Scene, an EGF Reader MUST play the associated video resource from its beginning to its end and MUST consider the Scene completed automatically once the video has been played fully at least once.

An EGF Reader MAY either start playback of the video resource automatically when the video_simple Scene becomes active or require an initial user action to start playback (such as pressing a Play button), depending on EGF Reader configuration and constraints (such as user settings, platform restrictions, or institutional policies).

An EGF Reader MUST provide a button (or functionally equivalent navigation control) that allows the learner to proceed to the next Scene in the EGF Sequence. This button MAY be displayed from the start of the Scene or once the Scene has been completed depending on the value of the enable-next-button-at-start attribute.

An EGF Reader MAY provide standard media playback controls (such as play, pause, seek, and volume) when rendering a video_simple Scene. The presence or absence of such controls does not affect conformance to this Specification.

Non-normative note: In typical implementations, the navigation control used to proceed to the next Scene is a button displayed below the video, shown disabled while the video is playing and enabled once the Scene has been completed.

Non-normative note: A video_simple Scene is intended to deliver lessons using a video resource.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="video_simple" href="assets/videos/video_simple_01.mp4" media-type="video/mp4" enable-next-button-at-start="false" id="video_simple_01" />
</manifest>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="video_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The item with the role video_simple:

If the value of the enable-next-button-at-start attribute of the item with the role video_simple is:

A video_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.1.4. audio_simple

audio_simple is a role designed to render a Scene that presents a single audio resource as its primary content. When rendering an audio_simple Scene, an EGF Reader MUST play the associated audio resource from its beginning to its end and MUST consider the Scene completed automatically once the audio has been played fully at least once.

An EGF Reader MAY either start playback of the audio resource automatically when the audio_simple Scene becomes active or require an initial user action to start playback (such as pressing a Play button), depending on EGF Reader configuration and constraints (such as user settings, platform restrictions, or institutional policies).

An EGF Reader MUST provide a button (or functionally equivalent navigation control) that allows the learner to proceed to the next Scene in the EGF Sequence. This button MAY be displayed from the start of the Scene or once the Scene has been completed depending on the value of the enable-next-button-at-start attribute.

An EGF Reader MAY provide standard media playback controls (such as play, pause, seek, and volume) when rendering an audio_simple Scene. The presence or absence of such controls does not affect conformance to this Specification.

Non-normative note: In typical implementations, the navigation control used to proceed to the next Scene is a button displayed below the audio, shown disabled while the audio is playing and enabled once the Scene has been completed.

Non-normative note: An audio_simple Scene is intended to deliver lessons using an audio resource. It can be used for learners to guess which song, voice, or instrument is used in a Scene.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="audio_simple" href="assets/audios/audio_simple_01.mp3" media-type="audio/mpeg" enable-next-button-at-start="false" id="audio_simple_01" />
</manifest>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="audio_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The item with the role audio_simple:

If the value of the enable-next-button-at-start attribute of the item with the role audio_simple is:

An audio_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.1.5. mcq_simple

mcq_simple is a role designed to render a Scene with exactly one multiple-choice question and four answer options, of which one is correct and three are incorrect.

When rendering an mcq_simple Scene, an EGF Reader MUST present the four answer options in such a way that the learner can select at most one of them.

When the learner selects an answer option, the EGF Reader:

After the learner has selected an answer option (whether correct or incorrect), the EGF Reader MUST treat that selection as final for the current mcq_simple Scene and MUST disable or otherwise prevent any further selection or change of answer options.

An mcq_simple Scene is considered complete when, and only when:

Once the Scene is complete, the EGF Reader MUST automatically advance to the next Scene in the EGF Sequence.

The question and each answer option MAY use any supported modality (text, image, video, or audio). For example, a text question MAY be combined with image-based answers, or an audio question MAY be combined with text-based answers.

An EGF Reader MAY provide additional accessibility features (for example, reduced motion or extended feedback duration), provided that it still automatically advances as required by this role. An EGF Reader MAY also provide a user setting to configure the delay (if any) between completion of the Scene and automatic advancement. Any such setting MUST NOT disable automatic advancement.

Non-normative note: An mcq_simple Scene is intended to display a multiple-choice question, either as text, as an image, as a video, or as audio, along with four answer options. Each answer option can also be displayed as text, as an image, as video, or as audio.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="mcq_simple" href="mcq_simple_01.xml" media-type="application/xml" id="mcq_simple_01" />
</manifest>

Then create an XML file (example mcq_simple_01.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<mcq_simple>
    <item role="mcq_question_image" href="assets/images/mcq_image_question.jpg" media-type="image/jpeg" id="mcq_question_image" />
    <item role="mcq_good_answer_feedback_audio" href="assets/audios/mcq_good_answer_feedback_audio.mp3" media-type="audio/mpeg" id="mcq_good_answer_feedback_audio" />
    <item role="mcq_wrong_answer_feedback_audio" href="assets/audios/mcq_wrong_answer_feedback_audio.mp3" media-type="audio/mpeg" id="mcq_wrong_answer_feedback_audio" />

    <item role="good_answer_image" href="assets/images/good_answer_image.jpg" media-type="image/jpeg" id="good_answer_image" />
    <item role="wrong_answer_image1" href="assets/images/wrong_answer_image1.jpg" media-type="image/jpeg" id="wrong_answer_image1" />
    <item role="wrong_answer_image2" href="assets/images/wrong_answer_image2.jpg" media-type="image/jpeg" id="wrong_answer_image2" />
    <item role="wrong_answer_image3" href="assets/images/wrong_answer_image3.jpg" media-type="image/jpeg" id="wrong_answer_image3" />
</mcq_simple>

For a text-based question and answer options, the same structure applies, but the question and answer options use the *_text variants. Each *_text item MUST provide its text either inline as character data or as an external text/plain resource referenced by the href attribute, as shown in the examples below.

Inline example:

<item role="mcq_question_text" media-type="text/plain" id="mcq_question_text">Which city is the capital of France?</item>

<item role="good_answer_text" media-type="text/plain" id="good_answer_text">Paris</item>
<item role="wrong_answer_text1" media-type="text/plain" id="wrong_answer_text1">London</item>
<item role="wrong_answer_text2" media-type="text/plain" id="wrong_answer_text2">Berlin</item>
<item role="wrong_answer_text3" media-type="text/plain" id="wrong_answer_text3">Rome</item>

External file example:

<item role="mcq_question_text" href="assets/texts/mcq_question.txt" media-type="text/plain" id="mcq_question_text" />

<item role="good_answer_text" href="assets/texts/mcq_good_answer.txt" media-type="text/plain" id="good_answer_text" />
<item role="wrong_answer_text1" href="assets/texts/mcq_wrong_answer1.txt" media-type="text/plain" id="wrong_answer_text1" />
<item role="wrong_answer_text2" href="assets/texts/mcq_wrong_answer2.txt" media-type="text/plain" id="wrong_answer_text2" />
<item role="wrong_answer_text3" href="assets/texts/mcq_wrong_answer3.txt" media-type="text/plain" id="wrong_answer_text3" />

For an audio-based question and answer options, the same structure applies, but the roles and MIME types use the *_audio variants, as in:

<item role="mcq_question_audio" href="assets/audios/question_audio.mp3" media-type="audio/mpeg" id="mcq_question_audio" />

<item role="good_answer_audio" href="assets/audios/good_answer_audio.mp3" media-type="audio/mpeg" id="good_answer_audio" />
<item role="wrong_answer_audio1" href="assets/audios/wrong_answer_audio1.mp3" media-type="audio/mpeg" id="wrong_answer_audio1" />
<item role="wrong_answer_audio2" href="assets/audios/wrong_answer_audio2.mp3" media-type="audio/mpeg" id="wrong_answer_audio2" />
<item role="wrong_answer_audio3" href="assets/audios/wrong_answer_audio3.mp3" media-type="audio/mpeg" id="wrong_answer_audio3" />

For a video-based question and answer options, the same structure applies, but the roles and MIME types use the *_video variants, as in:

<item role="mcq_question_video" href="assets/videos/question_video.mp4" media-type="video/mp4" id="mcq_question_video" />

<item role="good_answer_video" href="assets/videos/good_answer_video.mp4" media-type="video/mp4" id="good_answer_video" />
<item role="wrong_answer_video1" href="assets/videos/wrong_answer_video1.mp4" media-type="video/mp4" id="wrong_answer_video1" />
<item role="wrong_answer_video2" href="assets/videos/wrong_answer_video2.mp4" media-type="video/mp4" id="wrong_answer_video2" />
<item role="wrong_answer_video3" href="assets/videos/wrong_answer_video3.mp4" media-type="video/mp4" id="wrong_answer_video3" />

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="mcq_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The items with the role mcq_good_answer_feedback_audio or mcq_wrong_answer_feedback_audio:

If any of the roles mcq_question_image, good_answer_image, wrong_answer_image1, wrong_answer_image2, or wrong_answer_image3 is used, the corresponding <item> element:

If any of the roles mcq_question_audio, good_answer_audio, wrong_answer_audio1, wrong_answer_audio2, or wrong_answer_audio3 is used, the corresponding <item> element:

If any of the roles mcq_question_text, good_answer_text, wrong_answer_text1, wrong_answer_text2, or wrong_answer_text3 is used, the corresponding <item> element:

If any of the roles mcq_question_video, good_answer_video, wrong_answer_video1, wrong_answer_video2, or wrong_answer_video3 is used, the corresponding <item> element:

An mcq_simple Scene MUST be a valid XML file and MUST contain exactly 7 <item> child elements:

An mcq_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.1.6. hangman_simple

hangman_simple is a role designed to render a Scene that creates a simple hangman game.

Characters used in a hangman_simple Scene, including the value of answer_to_guess, MAY be any Unicode characters, including letters with diacritics, spaces, punctuation, and other non-ASCII characters. An EGF Reader MUST correctly render all characters that appear in the value of answer_to_guess and MUST provide a way for the learner to input or select each distinct character that is intended to be guessable in the Scene (for example, via a physical keyboard, a virtual keyboard, or a character selection interface).

When the learner validates a guessed character, the EGF Reader MUST determine whether that character is correct for the current hangman_simple Scene.

If the learner validates a character that has already been guessed in the current Scene, the EGF Reader MUST ignore it and MUST NOT change game state or scoring.

Each validated guess MUST be treated as final. The EGF Reader MUST NOT allow the learner to undo or modify that guess in a way that affects game state or scoring.

A hangman_simple Scene is considered complete when either:

Once the Scene is complete, the EGF Reader MUST automatically advance to the next Scene in the EGF Sequence.

An EGF Reader MAY provide additional accessibility features (for example, reduced motion or extended feedback duration) and MAY provide a user setting to configure the delay (if any) between completion of the Scene and automatic advancement, provided that automatic advancement still occurs as required by this role.

Non-normative note: The hangman_simple Scene is intended to provide an input where the player can type a character, with the hangman status shown above. A sound effect is played when the player validates either a correct or an incorrect character. The hangman status changes when the player types a wrong answer.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="hangman_simple" href="hangman_simple_01.xml" media-type="application/xml" id="hangman_simple_01" />
</manifest>

Then create an XML file (example hangman_simple_01.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<hangman_simple>
    <item role="hangman_status_01" href="assets/images/hangman_status_01.jpg" media-type="image/jpeg" id="hangman_status_01" />
    <item role="hangman_status_02" href="assets/images/hangman_status_02.jpg" media-type="image/jpeg" id="hangman_status_02" />
    <item role="hangman_status_03" href="assets/images/hangman_status_03.jpg" media-type="image/jpeg" id="hangman_status_03" />
    <item role="hangman_status_04" href="assets/images/hangman_status_04.jpg" media-type="image/jpeg" id="hangman_status_04" />
    <item role="hangman_status_05" href="assets/images/hangman_status_05.jpg" media-type="image/jpeg" id="hangman_status_05" />
    <item role="hangman_status_06" href="assets/images/hangman_status_06.jpg" media-type="image/jpeg" id="hangman_status_06" />
    <item role="hangman_status_07" href="assets/images/hangman_status_07.jpg" media-type="image/jpeg" id="hangman_status_07" />
    <item role="hangman_status_08" href="assets/images/hangman_status_08.jpg" media-type="image/jpeg" id="hangman_status_08" />
    <item role="hangman_status_09" href="assets/images/hangman_status_09.jpg" media-type="image/jpeg" id="hangman_status_09" />

    <item role="good_answer_audio" href="assets/audios/good_answer_audio.mp3" media-type="audio/mpeg" id="good_answer_audio" />
    <item role="wrong_answer_audio" href="assets/audios/wrong_answer_audio.mp3" media-type="audio/mpeg" id="wrong_answer_audio" />

    <item role="answer_to_guess" value="PLACE THE ANSWER TO GUESS HERE" case-sensitive="false" diacritic-sensitive="false" id="answer_to_guess" />
</hangman_simple>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="hangman_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The items whose role is one of the following: hangman_status_01 (hangman initial state), hangman_status_02, [...], hangman_status_09 (hangman final state):

The items with the role good_answer_audio or wrong_answer_audio:

The item with the role answer_to_guess:

If the value of the case-sensitive attribute of the item with the role answer_to_guess is:

If the value of the diacritic-sensitive attribute of the item with the role answer_to_guess is:

Non-normative note: This Specification defines diacritic folding only as described above (Unicode NFD plus removal of combining marks, category Mn). It does not define any additional Unicode normalization or character-equivalence rules, such as treating ligatures (for example "œ") as equivalent to multi-character sequences (for example "oe").

A hangman_simple Scene MUST be a valid XML file and MUST contain exactly the 12 <item> child elements listed in the example above.

A hangman_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.1.7. question_simple

question_simple is a role designed to render a Scene that presents a single open-ended question and lets the learner enter an answer. The Scene then evaluates the learner's answer against the expected answer and provides feedback.

When rendering a question_simple Scene, an EGF Reader MUST display the question resource and MUST provide an input control that allows the learner to enter an answer (for example, a text field, a virtual keyboard, or any equivalent input mechanism).

When the learner submits an answer, the EGF Reader MUST compare the learner’s submitted answer with the value of the item whose role is answer_to_guess, taking into account the case-sensitive and diacritic-sensitive attributes as defined below.

After the learner has submitted an answer (whether correct or incorrect), the EGF Reader MUST treat that submission as final for the current question_simple Scene and MUST disable or otherwise prevent any further changes to the submitted answer.

Once a question_simple Scene has been completed based solely on the submission of an answer by the learner and the end of the audio feedback associated with that submission, the EGF Reader MUST automatically advance to the next Scene in the EGF Sequence.

An EGF Reader MAY provide additional accessibility features (for example, reduced motion or extended feedback duration) and MAY provide a user setting to configure the delay (if any) between completion of the Scene and automatic advancement, provided that automatic advancement still occurs as required by this role.

Characters used in a question_simple Scene, including the value of answer_to_guess and any text displayed to the learner, MAY be any Unicode characters, including letters with diacritics, spaces, punctuation, and other non-ASCII characters. An EGF Reader MUST correctly render all characters that appear in the value of answer_to_guess and MUST provide a way for the learner to enter each distinct character that appears in the value of answer_to_guess (for example, via a physical keyboard, a virtual keyboard, or a character selection interface).

Non-normative note: A question_simple Scene is intended for short free-text answers such as vocabulary, dates, or simple facts. The question itself may be presented as text, an image, audio, or video. A typical implementation displays the question at the top of the screen, provides an input field for the learner’s answer below it, then plays a "correct" or "incorrect" sound after the learner submits an answer.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="question_simple" href="question_simple_01.xml" media-type="application/xml" id="question_simple_01" />
</manifest>

Then create an XML file (example question_simple_01.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<question_simple>
    <item role="question_text" href="assets/texts/questions_01.txt" media-type="text/plain" id="question_text" />

    <item role="good_answer_feedback_audio" href="assets/audios/good_answer_audio.mp3" media-type="audio/mpeg" id="good_answer_feedback_audio" />
    <item role="wrong_answer_feedback_audio" href="assets/audios/wrong_answer_audio.mp3" media-type="audio/mpeg" id="wrong_answer_feedback_audio" />

    <item role="answer_to_guess" value="Paris" case-sensitive="false" diacritic-sensitive="false" id="answer_to_guess" />
</question_simple>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="question_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

For an image-based question, the same structure applies, but the question uses the question_image role with an external image resource:

<item role="question_image" href="assets/images/question_image.jpg" media-type="image/jpeg" id="question_image" />

For an audio-based question, the same structure applies, but the question uses the question_audio role:

<item role="question_audio" href="assets/audios/question_audio.mp3" media-type="audio/mpeg" id="question_audio" />

For a video-based question, the same structure applies, but the question uses the question_video role:

<item role="question_video" href="assets/videos/question_video.mp4" media-type="video/mp4" id="question_video" />

If the role question_text is used, the corresponding <item> element:

If the role question_image is used, the corresponding <item> element:

If the role question_audio is used, the corresponding <item> element:

If the role question_video is used, the corresponding <item> element:

Exactly one of the roles question_text, question_image, question_audio, or question_video MUST be used in a given question_simple Scene to represent the question.

The items with the role good_answer_feedback_audio or wrong_answer_feedback_audio:

The item with the role answer_to_guess:

If the value of the case-sensitive attribute of the item with the role answer_to_guess is:

If the value of the diacritic-sensitive attribute of the item with the role answer_to_guess is:

Non-normative note: This Specification defines diacritic folding only as described above (Unicode NFD plus removal of combining marks, category Mn). It does not define any additional Unicode normalization or character-equivalence rules, such as treating ligatures (for example "œ") as equivalent to multi-character sequences (for example "oe").

A question_simple Scene MUST be a valid XML file and MUST contain exactly 4 <item> child elements:

A question_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.1.8. true_or_false_simple

true_or_false_simple is a role designed to render a Scene that presents exactly one statement (or question) and two answer options: True and False. Exactly one of the two options is correct.

When rendering a true_or_false_simple Scene, an EGF Reader MUST:

When the learner selects an answer option, the EGF Reader:

After the learner has selected an option (whether correct or incorrect), the EGF Reader MUST treat that selection as final for the current true_or_false_simple Scene and MUST disable or otherwise prevent any further selection or change.

A true_or_false_simple Scene is considered complete when, and only when:

Once the Scene is complete, the EGF Reader MUST automatically advance to the next Scene in the EGF Sequence.

An EGF Reader MAY provide additional accessibility features (for example, reduced motion or extended feedback duration) and MAY provide a user setting to configure the delay (if any) between completion of the Scene and automatic advancement, provided that automatic advancement still occurs as required by this role.

Non-normative note: A true_or_false_simple Scene is intended for quick binary checks (for example, verifying a simple fact, a vocabulary statement, or a short comprehension prompt). The question itself MAY be presented as text, an image, audio, or video. A typical implementation displays the question prominently and offers two clear response controls (True and False). After the learner selects an option, the EGF Reader plays a corresponding "correct" or "incorrect" feedback sound. On smartphones and other touch devices, the EGF Reader MAY additionally provide gesture shortcuts, such as swiping left to choose False and swiping right to choose True, provided that equivalent accessible controls remain available (for example, buttons) and that the gesture cannot trigger an accidental selection without a clear, intentional action.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="true_or_false_simple" href="true_or_false_simple_01.xml" media-type="application/xml" id="true_or_false_simple_01" />
</manifest>

Then create an XML file (example true_or_false_simple_01.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<true_or_false_simple>
    <item role="question_text" href="assets/texts/true_or_false_question_01.txt" media-type="text/plain" id="question_text" />

    <item role="good_answer_feedback_audio" href="assets/audios/good_answer_feedback_audio.mp3" media-type="audio/mpeg" id="good_answer_feedback_audio" />
    <item role="wrong_answer_feedback_audio" href="assets/audios/wrong_answer_feedback_audio.mp3" media-type="audio/mpeg" id="wrong_answer_feedback_audio" />

    <item role="correct_answer" value="true" id="correct_answer" />
</true_or_false_simple>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="true_or_false_simple_01" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

For an image-based question, the same structure applies, but the question uses the question_image role with an external image resource:

<item role="question_image" href="assets/images/question_image.jpg" media-type="image/jpeg" id="question_image" />

For an audio-based question, the same structure applies, but the question uses the question_audio role:

<item role="question_audio" href="assets/audios/question_audio.mp3" media-type="audio/mpeg" id="question_audio" />

For a video-based question, the same structure applies, but the question uses the question_video role:

<item role="question_video" href="assets/videos/question_video.mp4" media-type="video/mp4" id="question_video" />

If the role question_text is used, the corresponding <item> element:

If the role question_image is used, the corresponding <item> element:

If the role question_audio is used, the corresponding <item> element:

If the role question_video is used, the corresponding <item> element:

Exactly one of the roles question_text, question_image, question_audio, or question_video MUST be used in a given true_or_false_simple Scene to represent the question.

The items with the role good_answer_feedback_audio or wrong_answer_feedback_audio:

The item with the role correct_answer:

A true_or_false_simple Scene MUST be a valid XML file and MUST contain exactly 4 <item> child elements:

A true_or_false_simple Scene MUST be placed somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ 9.1.2. Special Scenes

§ 9.1.2.1. game_title_simple

game_title_simple is a role designed to render a Special Scene that presents the main title of an EGF Game as its primary content.

When rendering a game_title_simple Scene, an EGF Reader:

Once the learner activates the control to start the game, the EGF Reader MUST navigate to the next Scene in the EGF Sequence and begin the Gameplay Session. When the learner activates the control to show the credits, the EGF Reader MUST navigate to the Credits Scene.

Non-normative note: A game_title_simple Scene is typically implemented as a title screen that displays a representative image of the game (often the same artwork used for the egf_cover role), with a “Start” button to begin the game and a “Credits” button to show the credits, all accompanied by a looping music track.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="game_title_simple" href="game_title.xml" media-type="application/xml" id="game_title" />
</manifest>

Then create an XML file (for example, game_title.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<game_title_simple>
    <item role="game_title_image" href="assets/images/game_title_image.jpg" media-type="image/jpeg" id="game_title_image" />
    <item role="game_title_audio" href="assets/audios/game_title_audio.mp3" media-type="audio/mpeg" id="game_title_audio" />
</game_title_simple>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The item with the role game_title_image:

The item with the role game_title_audio:

A game_title_simple Scene MUST be a valid XML file.

A game_title_simple Scene MUST be placed at the beginning of the EGF Sequence.

§ 9.1.2.2. congratulations_simple

congratulations_simple is a role designed to render a Special Scene that displays a basic congratulations screen.

When rendering a congratulations_simple Scene, an EGF Reader:

After the congratulations_audio resource has finished playing, the EGF Reader MUST display a button (or functionally equivalent navigation control) that allows the learner to start a new Gameplay Session of the EGF Game (for example, a "Play again" button). This button MAY be displayed in a disabled state before the congratulations_audio resource has finished playing but MUST NOT be enabled before the congratulations_audio resource has finished playing. When the learner activates this control, the EGF Reader MUST:

An EGF Reader MAY also provide other controls on the congratulations_simple Scene (for example, a control to exit the game), but these additional controls MUST NOT be required in order to start a new Gameplay Session.

Non-normative note: In typical implementations, the navigation control used to start a new Gameplay Session of the EGF Game is a button displayed below the congratulations image, shown disabled while the congratulations_audio resource is playing and enabled once the congratulations_audio has finished playing.

Non-normative note: A congratulations_simple Scene is intended to display a congratulations image, with a button below it to play again that appears after an audio resource has finished playing.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="congratulations_simple" href="congratulations.xml" media-type="application/xml" id="congratulations" />
</manifest>

Then create an XML file (for example, congratulations.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<congratulations_simple>
    <item role="congratulations_image" href="assets/images/congratulations_image.jpg" media-type="image/jpeg" id="congratulations_image" />
    <item role="congratulations_audio" href="assets/audios/congratulations_audio.mp3" media-type="audio/mpeg" id="congratulations_audio" />
</congratulations_simple>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The item with the role congratulations_image:

The item with the role congratulations_audio:

A congratulations_simple Scene MUST be a valid XML file.

A congratulations_simple Scene MUST be the antepenultimate Scene in the EGF Sequence, immediately followed by the Game Over Scene.

§ 9.1.2.3. game_over_simple

game_over_simple is a role designed to render a Special Scene that displays a basic game over screen.

When rendering a game_over_simple Scene, an EGF Reader:

After the game_over_audio resource has finished playing, the EGF Reader MUST display a button (or functionally equivalent navigation control) that allows the learner to start a new Gameplay Session of the EGF Game (for example, a "Play again" button). This button MAY be displayed in a disabled state before the game_over_audio resource has finished playing but MUST NOT be enabled before the game_over_audio resource has finished playing. When the learner activates this control, the EGF Reader MUST:

An EGF Reader MAY also provide other controls on the game_over_simple Scene (for example, a control to exit the game or to show the credits directly), but these additional controls MUST NOT be required in order to start a new Gameplay Session.

Non-normative note: In typical implementations, the navigation control used to start a new Gameplay Session of the EGF Game is a button displayed below the game over image, shown disabled while the game_over_audio resource is playing and enabled once the game_over_audio has finished playing.

Non-normative note: A game_over_simple Scene is intended to display a game over image and clearly indicate that the current Gameplay Session has ended, typically after the learner has made too many mistakes. A common implementation also places the "Play again" control below the image, but the exact user interface layout is up to the EGF Reader.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="game_over_simple" href="game_over.xml" media-type="application/xml" id="game_over" />
</manifest>

Then create an XML file (for example, game_over.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<game_over_simple>
    <item role="game_over_image" href="assets/images/game_over_image.jpg" media-type="image/jpeg" id="game_over_image" />
    <item role="game_over_audio" href="assets/audios/game_over_audio.mp3" media-type="audio/mpeg" id="game_over_audio" />
</game_over_simple>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

The item with the role game_over_image:

The item with the role game_over_audio:

A game_over_simple Scene MUST be a valid XML file.

A game_over_simple Scene MUST be the penultimate Scene in the EGF Sequence, immediately followed by the Credits Scene.

§ 9.1.2.4. credits_simple

credits_simple is a role designed to render a Scene that displays the credits of the EGF Game.

Non-normative note: A credits_simple Scene is intended to display the EGF Game's credits, with a button at the end to exit the EGF Game and another to return to the Game Title Scene. It is typically accessed from the Game Title Scene (for example, via a "Credits" button), but other navigation paths (such as from a game_over_simple Scene) MAY also be provided by the EGF Reader.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="credits_simple" href="credits.xml" media-type="application/xml" id="credits" />
</manifest>

Then create an XML file (for example, credits.xml), with this structure:

<?xml version="1.0" encoding="UTF-8"?>
<credits_simple>
    <item role="credit_field">
        <item role="label">Creator</item>
        <item role="content">Hervé Yvis</item>
    </item>
    <item role="credit_field">
        <item role="label">Images</item>
        <item role="content">Béatrice Yvis</item>
    </item>
    <item role="credit_field">
        <item role="label">Pronunciation of the letters</item>
        <item role="content">PodcastFrancaisFacile | https://www.podcastfrancaisfacile.com/cours/alphabet-francais-cours-1b.html</item>
    </item>
    <item role="credit_field">
        <item role="label">Teacher's voice</item>
        <item role="content">David François Abdoul Majid</item>
    </item>
    <item role="credit_field">
        <item role="label">Victory sound</item>
        <item role="content">OrangeMcMuffin | https://freesound.org/s/423021/ | Licence : CC BY 3.0 | No changes made</item>
    </item>
</credits_simple>

Then add the Scene to the EGF Sequence. For example:

<sequence>
    <scene ref="game_title" />
    <!-- Other <scene> elements may appear here -->
    <!-- Example: <scene ref="mcq_simple_01" /> -->
    <!-- Other <scene> elements may appear here -->
    <scene ref="congratulations" />
    <scene ref="game_over" />
    <scene ref="credits" />
</sequence>

A credits_simple Scene MUST contain one or more child items with the role credit_field.

Each item with the role credit_field MUST contain exactly two child items: one item with the role label and one item with the role content.

The text value of both child items (label and content) MUST be provided as the character data of the <item> element.

Non-normative note: Although the Credits Scene is always the last Scene in the EGF Sequence, EGF Readers typically navigate to it only in response to explicit user actions (for example, a "Credits" button on the Game Title or Game Over Scenes), rather than automatically from the preceding Scenes.

A credits_simple Scene MUST be a valid XML file.

A credits_simple Scene MUST be placed at the very end of the EGF Sequence, right after the Game Over Scene.

§ 9.1.3. Non-Scene Roles

§ 9.1.3.1. max_wrong_answers

max_wrong_answers is a role designed to configure when the Game Over Scene MUST be displayed.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="max_wrong_answers" value="5" id="max_wrong_answers" />
</manifest>

Then add the Setting to the EGF Settings. For example:

<settings>
     <!-- Other <setting> elements may appear here -->
    <setting ref="max_wrong_answers" />
    <!-- Other <setting> elements may appear here -->
</settings>

The item with the role max_wrong_answers MUST have an attribute named value, whose value MUST be a positive integer (1 or greater) expressed in base-10 digits and defines the maximum number of wrong answers the learner is allowed to give before the Game Over Scene is displayed.

At the start of each Gameplay Session, the wrong-answer counter MUST be initialized to 0.

An EGF Reader MUST maintain a running counter of wrong answers across the whole EGF Game. For each Scene Role that defines wrong answers, this counter MUST be incremented as follows:

Scenes with the Roles text_simple, image_simple, video_simple, audio_simple, game_title_simple, congratulations_simple, game_over_simple, and credits_simple MUST NOT modify this counter.

When the wrong-answer counter becomes greater than or equal to the value defined by the item whose role is max_wrong_answers, the EGF Reader MUST, after completing the required role-specific behavior of the current Scene (for example, finishing playback of feedback audio), override the normal progression of the <sequence> and navigate directly to the Game Over Scene (the Scene whose Manifest Item has the role game_over_simple).

Non-normative note: For example, in an mcq_simple Scene, the required role-specific behavior includes playing the appropriate feedback audio for the selected answer. The Game Over Scene SHOULD be displayed only after this feedback has finished playing.

For example:

<item role="max_wrong_answers" value="5" id="max_wrong_answers" />

In this example, the EGF Reader MUST display the Game Over Scene after the learner has accumulated 5 wrong-answer increments as defined above.

Since max_wrong_answers is not a Scene, it MUST NOT be placed in the EGF Sequence.

Use of this role is MANDATORY: an EGF Core File MUST define a max_wrong_answers configuration as specified in Section 8.5.

§ 9.1.3.2. background_audio

background_audio is a role designed to play a background audio sound across a defined range of Scenes in an EGF Game.

Playback lifetime

If a background_audio Setting is defined, an EGF Reader:

Interaction with foreground audio

Several Scene Roles defined in this Specification associate one or more foreground audio resources with a Scene (for example: audio_simple, good_answer_audio, wrong_answer_audio, congratulations_audio, and other Roles defined in this Specification).

When a background_audio Setting is defined:

Optionally, an EGF Reader MAY provide a user control to adjust how much background_audio is reduced while foreground audio is playing (for example, via a volume slider, percentage, or decibel reduction setting). If provided, the EGF Reader MUST ensure that the user control cannot reduce background_audio attenuation below the minimum level required to keep foreground audio clearly audible and intelligible.

Non-normative note: An EGF Package MAY define several background_audio items with different scope ranges to use different background music during different stages of the EGF Game.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="background_audio" href="assets/audios/background_audio_01.mp3" media-type="audio/mpeg" scope-from="video_simple_01" scope-to="hangman_simple_01" id="background_audio_01" />
</manifest>

Then add the Setting to the EGF Settings. For example:

<settings>
     <!-- Other <setting> elements may appear here -->
    <setting ref="background_audio_01" />
    <!-- Other <setting> elements may appear here -->
</settings>

The item with the role background_audio:

Non-normative note: Authors of EGF Games are encouraged to avoid overlapping scope ranges for different background_audio items. If such overlaps occur, the behavior is implementation-dependent; for example, an EGF Reader MAY fade out the previous background_audio and fade in the new one when the overlap begins.

Backward compatibility

In EGF 1.0, items with role background_audio did not define scope-from or scope-to attributes. For EGF Packages whose EGF Core File declares version="1.0", a Conforming EGF 1.1 Reader MUST assume an implicit scope equivalent to the Gameplay Session as defined in Section 4: as if:

If a background_audio item in an EGF 1.1 Package omits one or both of the attributes scope-from or scope-to, a Conforming EGF 1.1 Reader MUST treat that item as if scope-from and scope-to were set to the default values described above for EGF 1.0 Packages.

An EGF Reader MAY provide additional features related to background audio control (for example, volume adjustment or mute/unmute). The presence or absence of such controls does not affect conformance to this Specification.

Since background_audio is not a Scene, it MUST NOT be placed in the EGF Sequence.

Use of this role is OPTIONAL but RECOMMENDED.

§ 9.1.3.3. egf_cover

egf_cover is a role used to reference the cover image of the EGF Game. It is not used directly in the game itself, but MAY be displayed in the library view of an EGF Reader.

Non-normative note: The image file referenced by the role egf_cover is recommended to have an aspect ratio of 5:6 (width:height).

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="egf_cover" href="assets/images/egf_cover.jpg" media-type="image/jpeg" id="egf_cover" />
</manifest>

The item with the role egf_cover:

Since egf_cover is not a Scene, it MUST NOT be placed in the EGF Sequence.

Use of this role is OPTIONAL but RECOMMENDED.

§ 9.1.3.4. foreground_audio

foreground_audio is a role designed to play a foreground audio resource at the beginning of a specific Scene.

Playback behavior

For each item whose role is foreground_audio, an EGF Reader:

Interaction with background_audio

No additional requirements are defined for interaction with background_audio beyond those already specified in Section 9.1.3.2. In particular, foreground_audio is considered a foreground audio resource for the purposes of background_audio behavior.

Non-normative note: An EGF Package MAY define several foreground_audio items associated with different Scenes in order to play distinct event sounds when those Scenes become active.

To use this role, implementations MUST include the following line in the EGF Manifest:

<manifest>
    <!-- Other <item> elements may appear here -->
    <item role="foreground_audio" href="assets/audios/foreground_audio_01.mp3" media-type="audio/mpeg" scene-ref="image_simple_01" id="foreground_audio_01" />
</manifest>

Then add the Setting to the EGF Settings. For example:

<settings>
     <!-- Other <setting> elements may appear here -->
    <setting ref="foreground_audio_01" />
    <!-- Other <setting> elements may appear here -->
</settings>

The item with the role foreground_audio:

An EGF Reader MAY provide additional features related to foreground audio control (for example, volume adjustment or mute/unmute). The presence or absence of such controls does not affect conformance to this Specification.

Since foreground_audio is not a Scene, it MUST NOT be placed in the EGF Sequence.

§ 9.2. Custom Roles

For the purposes of this section, Core Roles, Custom Roles, and Valid Roles are defined in Section 4. Custom Roles are intended to support experimental or implementation-specific features. This section defines how Custom Roles MAY be used and how they affect conformance.

Custom Roles MAY be used:

The semantics of Custom Roles are outside the scope of this Specification. They MAY be defined by private agreements between specific EGF Readers and EGF Editors, by institutional profiles, or by future versions of EGF.

Any role name that is not a Core Role and does not start with the prefix "x-" MUST NOT be considered a valid Custom Role under this Specification. Such a role name MUST be treated as an error by validation tools and MAY indicate a malformed EGF Package or an attempt to use a future version of EGF without declaring the appropriate version.

Readers

An EGF Reader that does not implement the semantics of a given Custom Role:

In all cases, the Reader MAY present a warning to the user or to implementers (for example, via a log), but MUST NOT crash or terminate abnormally solely due to the presence of Custom Roles.

Editors

An EGF Editor that allows authors to create or use Custom Roles:

Conformance classes

For the purposes of conformance:

§ 10. Versioning and Extensibility

§ 10.1. EGF version

The EGF Core File MUST declare its version in the version attribute of the <egf> root element. The value of this attribute MUST use a "major.minor" scheme (for this Specification: "1.1", and for future versions for example "1.2").

An EGF Reader that claims conformance to EGF 1.1:

MUST correctly process any EGF Package whose EGF Core File declares <egf version="1.0"> or <egf version="1.1"> and MUST NOT reject such an EGF Package solely on the basis of its version.

MAY attempt to process EGF Packages with the same major version and a higher minor version (for example, version="1.2") using the rules in Section 10.2.

MUST NOT claim full conformance to any EGF version higher than the one it implements.

If the major version declared in the version attribute of the <egf> root element is greater than 1 (for example, version="2.0"), an EGF Reader MAY reject the EGF Package or open it in a degraded or "experimental" mode, but in any case it MUST NOT claim conformance to the EGF 1.1 Specification.

EGF 1.1 is backward compatible with EGF 1.0, and any Reader claiming conformance to EGF 1.1 MUST be able to open and correctly process all conforming EGF 1.0 Packages.

Non-normative note: A Package whose EGF Core File declares version="1.0" is not a Conforming EGF 1.1 Package. It may conform to EGF 1.0. This section defines EGF 1.1 Reader behavior for backward compatibility with EGF 1.0 Packages.

For EGF Packages whose EGF Core File declares version="1.0", repeated values of the ref attribute in <scene> elements within <sequence> MAY occur and MUST NOT cause rejection by a Conforming EGF 1.1 Reader. A Conforming EGF 1.1 Reader MUST treat each <scene> element in a version="1.0" <sequence> as a separate step in the Sequence and MUST NOT de-duplicate, merge, or skip <scene> elements solely because they reference the same ref value. If the same Manifest Item id is referenced by multiple <scene> elements, the EGF Reader MUST execute the role-specific behavior each time that <scene> element is encountered in the Sequence. If a Scene Role defines per-Scene completion state (for example, "answer selected" in mcq_simple), that per-Scene state MUST be scoped to the <scene> element occurrence in the Sequence, not to the Manifest Item id, for EGF 1.0 Packages.

§ 10.2. Unknown roles and elements

An EGF Reader MAY encounter roles, elements, or attributes that are not defined in this Specification.

If a Manifest Item has a role that is unknown to the EGF Reader and is never referenced from the EGF Sequence, the EGF Reader MAY safely ignore it.

If a Scene in the EGF Sequence references an item whose role is unknown to the EGF Reader, the EGF Reader:

MAY render it using a generic fallback (for example, displaying the underlying resource as plain content), or

MAY skip the Scene and continue with the next Scene in the Sequence.

In both cases, the EGF Reader MAY present a warning to the user, but MUST NOT crash or terminate abnormally solely due to the presence of unknown roles, elements, or attributes.

EGF Readers and EGF Editors MUST ignore any additional elements or attributes they do not understand, unless this Specification explicitly states otherwise. Unknown content by itself MUST NOT invalidate the entire EGF Package.

§ 11. EGF rendering

This Specification defines the EGF file format and the semantics of the roles listed in Section 9. It does not prescribe any particular user interface, layout, or rendering technology.

An EGF Reader MUST use the EGF Sequence as the primary ordering of Scenes and MUST respect the semantics and constraints associated with each Role (for example, that a video_simple Scene plays a video resource from start to finish). Unless a Role specifies different navigation semantics, the Reader MUST present Scenes in the order in which they appear in the EGF Sequence.

Roles MAY define explicit navigation actions (for example, a "Play again" control) that cause the EGF Reader to jump to an earlier Scene in the Sequence, skip Scenes, or initiate a new Gameplay Session. Such navigation remains compliant with this Specification, as long as it follows the rules defined for the corresponding Role.

Apart from these requirements, implementers are free to render an EGF Game in any way they choose (for example, using native widgets, HTML, or a game engine). Non-normative UI guidelines and examples MAY be published in separate EGF UI guides; following those guides is OPTIONAL and is not required to claim conformance to this Specification.

§ 12. Conformance

This section defines what it means to conform to the EGF 1.1 Specification. The conformance model is defined for:

Unless otherwise stated, all requirements in this section are normative.

§ 12.1. Conforming EGF 1.1 Package

Non-normative note: This section summarizes the normative requirements defined throughout the specification and is intended as a conformance checklist.

An EGF Package is a Conforming EGF 1.1 Package if and only if all of the following conditions are met:

§ ZIP container

§ Directory structure and container.xml

§ EGF Core File

The file referenced by the full-path attribute of <rootfile> MUST be a well-formed XML document.

The root element of this document MUST be <egf> and MUST have a version attribute whose value is "1.1".

The <egf> root element MUST contain exactly one <metadata> element, exactly one <manifest> element, exactly one <sequence> element, and exactly one <settings> element.

§ Metadata

The <metadata> element MUST declare the namespaces:

The <metadata> element MUST contain:

The <metadata> element MUST contain a <meta> element with property="dcterms:modified" whose value is an xsd:dateTime in Coordinated Universal Time (UTC) representing the last modification time of the EGF Package.

§ Manifest

All child elements of <manifest> MUST be <item> elements.

Each <item> element in <manifest> MUST have:

All additional attributes required for each role (for example, href, media-type, value, case-sensitive) MUST be present and MUST satisfy the constraints defined in Section 9.

The EGF Manifest MUST include Manifest Items for:

The Manifest MUST contain exactly one item whose role is max_wrong_answers, with a value attribute that is a positive integer (1 or greater) expressed in base-10 digits.

§ Sequence

All child elements of <sequence> MUST be <scene> elements.

Each <scene> element MUST have a ref attribute whose value is the id of a Manifest Item.

Each Manifest Item id referenced from <sequence> MUST be referenced at most once within that sequence.

The EGF Sequence MUST include at least:

The Game Title Scene MUST be the first Scene in the EGF Sequence.

The Congratulations Scene MUST be the antepenultimate Scene in the EGF Sequence, immediately followed by the Game Over Scene.

The Game Over Scene MUST be the penultimate Scene in the EGF Sequence, immediately followed by the Credits Scene.

The Credits Scene MUST be the last Scene in the EGF Sequence.

All Scenes that use roles defined as "MUST be placed between the Game Title Scene and the Congratulations Scene" (for example, video_simple, audio_simple, mcq_simple, hangman_simple, and other Roles defined in this Specification) MUST appear somewhere between the Game Title Scene and the Congratulations Scene in the EGF Sequence.

§ Settings

All child elements of <settings> MUST be <setting> elements.

Each <setting> element MUST have a ref attribute whose value is the id of a Manifest Item defined in <manifest>.

There MUST be exactly one <setting> element whose ref attribute points to the Manifest Item with role="max_wrong_answers".

Any optional Settings (for example, the background_audio Setting) MUST satisfy all constraints defined for their corresponding roles in Section 9.

§ Resources, paths, and MIME types

All href and full-path values in the EGF Package MUST be expressed as relative paths, as defined in Section 4.

The resource referenced by each href MUST exist in the ZIP archive at the specified location.

All media-type attribute values MUST use valid MIME types and MUST comply with the allowed types for the corresponding roles, as defined in Section 9.

All referenced XML resources (such as Scene or Special Scene XML files) MUST be well-formed XML documents and MUST respect the structural constraints defined for their respective roles.

All text-based resources in an EGF Package MUST be encoded in UTF-8. This includes the EGF Core File, all referenced XML resources, and any text/plain resources. An EGF Reader MUST decode these resources as UTF-8.

An EGF Package that satisfies all of the requirements above and does not use any Custom Roles as defined in Section 9.2 MUST be considered a Conforming EGF 1.1 Package.

An EGF Package that satisfies all of the structural and semantic requirements of this section but uses one or more Custom Roles (that is, role names starting with "x-") MUST NOT be considered a Conforming EGF 1.1 Package. The labelling of such packages is described in Section 9.2.

§ 12.2. Conforming EGF Reader

An EGF Reader conforms to this Specification as a Conforming EGF 1.1 Reader if and only if it satisfies all of the following conditions:

§ Supported versions

§ Validation of package structure

The Reader MUST verify the presence and basic structure of:

The Reader MAY perform additional validation of conformance, but failure to fully validate MUST NOT cause the Reader to crash or terminate abnormally.

§ Roles and semantics

For all roles defined in Section 9 that the Reader claims to support, the Reader MUST implement the semantics and constraints described for those roles.

For any Scene whose role is defined in Section 9 and supported by the Reader, the Reader MUST:

The Reader MUST maintain and update the wrong-answer counter as defined for the max_wrong_answers role, and MUST display the Game Over Scene when the counter is greater than or equal to the configured max_wrong_answers value.

§ Sequence and navigation

The Reader MUST use the EGF Sequence as the primary ordering of Scenes, as defined in Section 11.

Unless a Role defines different navigation semantics, the Reader MUST present Scenes in the order in which they appear in the EGF Sequence.

For roles that define explicit navigation actions (for example, “Play again” controls on congratulations_simple and game_over_simple Scenes), the Reader MUST implement those actions as described in Section 9.

When a new Gameplay Session is initiated from a Special Scene (for example, from the congratulations_simple or game_over_simple Scene), the Reader MUST:

§ Handling unknown content

The Reader MUST ignore any additional elements or attributes it does not understand, unless this Specification explicitly states otherwise.

If a Manifest Item has an unknown role and is never referenced from the EGF Sequence, the Reader MAY ignore it.

If the EGF Sequence references a Scene whose role is unknown to the Reader, the Reader:

In all cases, the Reader MAY present a warning to the user, but MUST NOT crash or terminate abnormally solely due to the presence of unknown roles, elements, or attributes.

§ Background audio and non-Scene roles

If the Reader claims to support background_audio, it MUST:

For any other non-Scene roles it supports, the Reader MUST implement the behavior described in Section 9 for those roles.

A software component that satisfies all of the requirements above is a Conforming EGF 1.1 Reader.

§ 12.3. Conforming EGF Editor

An EGF Editor conforms to this Specification as a Conforming EGF 1.1 Editor if and only if it satisfies all of the following conditions:

§ Package creation

For every EGF Package that it produces and labels as conformant to EGF 1.1, the Editor MUST generate a Conforming EGF 1.1 Package as defined in Section 12.1.

The Editor MAY support authoring modes or export options that do not produce conforming packages, but such packages MUST NOT be claimed to conform to the EGF 1.1 Specification.

§ Preservation of conformance

When opening and saving an existing Conforming EGF 1.1 Package without semantic changes (for example, simple metadata edits), the Editor SHOULD preserve conformance.

If the Editor cannot preserve conformance (for example, because it removes required Scenes or roles), it MUST NOT label the resulting package as conformant to EGF 1.1.

§ Use of roles and structures

When the Editor provides user-facing features to create Scenes and resources for the roles defined in Section 9, it MUST:

The Editor MUST enforce the structural constraints on the EGF Sequence for:

§ Versioning and extension

When generating an EGF Core File for EGF 1.1, the Editor MUST set version="1.1" on the <egf> root element.

If the Editor generates packages for future minor versions of EGF, it MUST set the version attribute appropriately, as described in Section 10.1.

If the Editor allows the creation of custom or extended roles, it MUST ensure that such roles:

When the Editor produces a package that contains one or more Custom Roles, it MAY label that package as an "EGF 1.1 Extended Package" or use an equivalent designation, but it MUST NOT claim that such a package is a Conforming EGF 1.1 Package.

§ 12.4. Conformance claims

Any software or content that claims conformance to this Specification:

Implementations MUST NOT claim conformance to future EGF versions (for example, "EGF 1.2" or higher) unless they fully implement those versions.