# Teacher User Manual - ChronoQuest

## Summary

- [1. Introduction](#1-introduction)
- [2. Installation](#2-installation)
- [2.1 Initial class setup](#21-initial-class-setup)
- [3. Teacher login and registration](#3-teacher-login-and-registration)
- [4. Edit teacher account](#4-edit-teacher-account)
- [5. Creation and selection of classes](#5-creation-and-selection-of-classes)
- [6. Teacher dashboard](#6-teacher-dashboard)
- [7. Inserting students into the class](#7-inserting-students-into-the-class)
- [8. Class teachers](#8-class-teachers)
- [9. Teams](#9-teams)
- [10. Quest](#10-quest)
- [11. Badges](#11-badges)
- [12. Powers](#12-powers)
- [13. Characters](#13-characters)
- [14. Punishments](#14-punishments)
- [15. Customizations](#15-customizations)
- [16. Materials](#16-materials)
- [17. Plugins](#17-plugins)
- [18. Test Creator: home, subjects and topics](#18-test-creator-home-subjects-and-topics)
- [19. Test Creator: questions](#19-test-creator-questions)
- [20. Test Creator: quiz](#20-test-creator-quiz)
- [21. Test Creator: books and evaluation rubrics](#21-test-creator-books-and-evaluation-rubrics)
- [22. Test Creator: print template](#22-test-creator-print-template)
- [23. Test Creator: import and export questions](#23-test-creator-import-and-export-questions)
- [24. Test Creator: my classes](#24-test-creator-my-classes)
- [25. Test Creator: teachers email](#25-test-creator-teachers-email)
- [26. Test Creator: administrators](#26-test-creator-administrators)

## 1. Introduction

ChronoQuest is an educational platform designed to transform classroom management into a path to missions, rewards, progress and responsibility. The program supports the teacher in conducting daily school activities, offering tools to organize classes and students, propose quests and exercises, follow up on assignments, assign badges and rewards, manage powers, punishments, materials and customizations.

This manual describes the use of the program from the teacher's point of view. The objective is to provide a practical guide to the functions available in the reserved area, following the real flow of the application: access, choice of class, dashboard, student management, creation of activities and control of results.

The ChronoQuest teaching area revolves around the selected class. After logging in, the teacher can enter one of their classes and administer its main elements: students, other associated teachers, teams, characters, quests, badges, powers, punishments, materials and additional content via plugins. Many functions are therefore linked to the active class: before working on the contents or student data it is important to verify that you have entered the correct class.

The system uses typical elements of educational gamification. Students can have a character, lives, mana, coins, levels, badges, powers, chests, and customizations. The teacher maintains control of these elements and uses them to reward progress, organize activities, correct assignments and make the work done in class more engaging.

The manual is intended for teachers who use ChronoQuest to:

- create and select your own classes;
- manage students and teachers connected to the class;
- monitor student progress from the dashboard;
- create quests, chapters and exercises;
- consult and evaluate submissions;
- assign rewards, badges, powers and punishments;
- upload teaching materials;
- configure characters, customizations and plugins.

The following sections will guide you step by step in the use of the individual areas of the program, maintaining an operational focus and oriented towards the actions that the teacher must carry out.

## 2. Installation

The initial ChronoQuest installation starts from the `public/install.php` page. This procedure is used to configure the database connection, set up email sending and prepare the main administrator account.

The procedure can be performed only if the program is not already installed. If the `.env` configuration file is already present, the installer displays a message indicating that ChronoQuest is already installed and directs you to the teacher login.

### Public folder of the site

ChronoQuest is organized by separating public files from the program's internal files. The folder that must be visible from the browser is `public`, because it contains the site's input files, including `index.php`, `install.php`, the assets and resources reachable by users.

The other project folders, such as `src`, `config`, `routes`, `sql`, `vendor`, and `var`, are system folders. They must not be exposed directly on the web, because they contain application code, configurations, libraries, SQL files or internal data.

The recommended configuration is to set the site's initial folder, also called document root, directly to `public`. In this way the visitor already enters the public part of the application and cannot navigate in the internal folders of the project.

If your hosting service does not allow you to set `public` as the home folder, you must use the `.htaccess` file in the project root folder. This file has two tasks:

- prevent direct access to system files and folders;
- automatically forward site requests to the `public` folder.

There is already a `.htaccess` configuration in the project which blocks access to folders such as `config`, `routes`, `src`, `sql`, `var`, `vendor` and redirects requests to `public`. If after publishing the site the home page is not opened correctly or `public/install.php` is not reached, you need to check that the `.htaccess` file is present in the root of the project and that the Apache server allows the use of rewrite rules.

In short: the user needs to see the site, not the internal structure of the program. If the domain root does not point directly to `public`, the `.htaccess` file must take care of the redirection.

### Data required

On the installation screen you need to fill in these data sets.

**Installation package**

The "Initial configuration" field allows you to choose the initial configuration to load into the database. The available options are:

- "Base configuration", to install an empty base;
- "Italian configuration", to install the Italian configuration;
- "English configuration", to install the English configuration.

Your choice determines which initial SQL package is imported during installation.

**Database**

This section is used to indicate where the MySQL database that ChronoQuest will use is located.

- "Database Host": address of the database server. This is usually `localhost`, if the database is on the same server as the site.
- "Database Name": name of the database to use for ChronoQuest.
- "Database Username": user name authorized to access the database.
- "Database Password": database user password. It can only be empty if the database server is configured this way.

The database must already exist and be reachable. The indicated user must have the necessary permissions to import the tables and data of the chosen package.

**Email**

This section configures the SMTP server used by the program to send emails, such as registration messages, notifications or automatic communications.

- "SMTP Host": mail server address.
- "Port": SMTP port, for example `465` for SSL or `587` for TLS, depending on the provider.
- "Encryption": type of encryption to use: SSL, TLS or None.
- "SMTP Username": email account username.
- "SMTP Password": email account password.
- "Sender Name": name displayed as sender, for example `ChronoQuest`.
- "Sender Email": sender email address. Must be a valid address.

The installer's default values offer `smtps.aruba.it`, `465` port, `ssl` encryption and `ChronoQuest` sender name, but they can be changed depending on the email service used.

**Administrator**

This section sets up the initial administrator account.

- "Admin Email": email of the main administrator.
- "Admin Password": administrator password. Must contain at least 8 characters.
- "Confirm Admin Password": repetition of the password, to avoid typing errors.

During installation, ChronoQuest updates the default administrator user present in the initial package, setting the indicated email and new password.

### Starting the installation

After filling in all the required fields, press the "Install ChronoQuest" button. The program checks the data entered, imports the chosen package into the database, updates the administrator password and creates the `.env` file with the configuration.

At the end, the message "Installation Complete" and the button to go to the teacher login are shown. From that moment the installation cannot be repeated from the same page, for security reasons.

## 2.1 Initial class setup

After installation, a reference class called `Test Class` is available in the system.

All teachers are part of `Test Class`. This class serves as a test environment to visualize the main features of the program and understand how content, characters, quests, punishments, powers and other elements of ChronoQuest are structured.

When a new class is created, the class starts out empty.

In particular, a new class does not contain:

- characters;
- quest;
- punishments;
- custom powers;
- some customizations;
- other contents configured in the test class.

Only the fixed elements foreseen by the system remain available, for example fixed powers.

To get started quickly, the teacher can import the elements already present in the `Test Class` into the new class.
To do this, enter the specific section and use the "Import from other class" command.

Examples:

- from the characters section you can import characters from another class;
- from the quest section you can import quests from another class;
- from the punishments section you can import punishments from another class;
- from the powers section you can import powers from another class;

In this way the new class can be prepared starting from `Test Class`, without having to manually recreate each element.

After configuring the class base, you can proceed with adding students.

## 3. Teacher login and registration

### Administrator login

After installation, the first login is from the `/loginDoc` page.

Initial credentials:

- username: `admin`;
- password: the one entered in the "Admin Password" field during installation.

If the credentials are correct, the user is authenticated as an administrator and is redirected to the `/docenti/classi` page, from which he or she can select or manage available classes.

### Teacher login

The teacher login page can be reached from `/loginDoc`.

Required fields:

- "Username": username of the teacher or administrator;
- "Password": password associated with the account.

In case of error, the message "incorrect username or password" is displayed. If the access is valid, the system opens the teacher area and leads to the choice of the class.

### New teacher registration

The registration of a new teacher can be reached from the `/registrazioneDoc` page, or from the "Register!" link. present on the teacher login screen.

Required fields:

- "Name";
- "Surname";
- "Username";
- "Email";
- "Password";
- "Confirm password";
- acceptance of the privacy/GDPR declaration.

Checks carried out:

- the first and last name cannot be empty;
- the username must be available;
- the email must have a valid format;
- the email must not already be used by another user;
- the email must be present in the list of enabled emails for registration, the emails are enabled by the administrator in the Test Creator section. This is for safety: only authorized teachers can register on the site (not students or other external people);
- password and password confirmation must match;
- privacy/GDPR confirmation is mandatory.

During compilation, username and email are also checked via automatic validation. If the username is already used or email is not enabled, the form reports the error before sending.

After successful sending, the system creates the teacher user with a status not yet validated and sends a validation email to the indicated address. The teacher can access only after opening the validation link received via email.

## 4. Edit teacher account

Changing the teacher account is available after logging in, from the user menu at the top right, "Profile" item. The corresponding page is `/docenti/profilo`.

### Fields displayed

The page shows:

- "Name and surname": non-editable field;
- "Username": non-editable field;
- "Email": editable field;
- "Do you want to receive emails from the site?": choice "Yes" / "No";
- "API key Gemini": optional field to use the suggestion functions with Gemini;
- "Language": choice between default English and Italian;
- "New Password";
- "Confirm new password".

### Editing rules

The teacher can update email, email preferences, Gemini key, language and password.

Name, surname and username cannot be changed from this screen.

### Obtain a Gemini API key

To use Gemini-based features, the teacher must enter a personal API key in the profile.

Summary procedure:

- log in with a Google account to `https://aistudio.google.com/apikey`;
- accept, if requested, the Google AI Studio terms of service;
- create or select a Google Cloud project;
- press "Create API key";
- copy the generated key;
- paste the key in the "API key Gemini" field of the teacher profile;
- save changes.

The API key should be treated like a password: it should not be published, shared or placed in files accessible by other users. If you suspect that the key has been exposed, you should generate a new one and deactivate the old one.

The password is changed only if the "New password" field is filled in. If the teacher does not want to change it, he must leave both "New password" and "Confirm new password" blank.

Controls applied when saving:

- the email must be valid;
- the email must not already be used by another user;
- if a new password is entered, the two password fields must match;
- the language is saved only if the value is `en` or `it`.

To confirm the changes press "Save changes". If successful, the profile message updated correctly is shown.

## 5. Creation and selection of classes

Class management is available from the "My Classes" item in the side menu, or from the `/docenti/classi` page.

This page is used to choose the class to work on. The selected class determines the data shown in subsequent sections, including the Teacher Dashboard, students, quests, badges, powers, punishments and customizations.

### Class list

The page shows the classes associated with the teacher, grouped by school year.

For each class the following are visible:

- school year;
- class name;
- icon;
- associated color;
- "Selected" indication, if it is the currently active class;
- "Enter class" button;
- edit button.

By pressing "Enter class", the class is saved as the active class in the session and the system opens the Teacher Dashboard.

### Creating new class

To create a new class press "Insert new class".

Required fields:

- "Class name";
- "School year";
- "Class icon";
- "Class color".

Upon saving, the system:

- create the class;
- associates it with the current teacher;
- selects it automatically;
- redirects to the teacher dashboard.

If the class name is blank or the school year is invalid, the class is not created.

### Edit class

From the edit button on the class sheet you can update:

- class name;
- icon;
- color.

The school year is not changed from this screen.

If the modified class is the active one, the new data is also updated in the current session.

### Operational notes

Many pages in the teaching area require a selected class. If there is no active class, the system redirects to the `/docenti/classi` page.

A teacher can only enter the classes with which he is associated. If you try to open a class that is not linked to your account, your selection will be rejected.

## 6. Teacher dashboard

The teacher dashboard can be reached from `/docenti/dashboard` after selecting a class.

It is used to have a quick overview of the status of the students in the class: lives, shields, mana, coins, level, progress towards the next level and chosen character. It is the main control page to check the general progress of the class and quickly intervene on individual students.

### Data displayed

The table shows, for each student:

- surname and name;
- lives and shields available;
- mana available;
- coins owned;
- level;
- progress towards the next level;
- associated character;
- button to remove a heart;
- instant death button.

If a student has not yet chosen the character, the data linked to the character is not available and the table shows provisional values.

### Actions on individual students

Direct actions are available for each row:

- "Remove Heart": removes a heart from the selected student. A justification is required.
- "Instant death": resets the student's vital status and starts the punishment assignment procedure.

When a student loses all lives, the system asks to assign a punishment. It is possible:

- assign a random punishment among those available;
- choose an existing punishment;
- create a new punishment indicating description, days for submission and any image.

### Actions on selected students

The table allows multiple selection of students. After selecting one or more rows, the buttons at the top are activated:

- "Send Mail": opens the composition of a message addressed to the selected students.
- "Remove Heart": removes a heart from selected students. A justification is required.
- "Give Reward": assign experience points and/or coins to the selected students. A justification is required.

To assign a reward it is necessary to indicate at least a value between XP and coins. Motivation is used to communicate to students the reason for the reward.

### Operational notes

The Dashboard always works on the currently selected class. If no class has been selected, the system takes you to the class selection page.

Changes made from the Dashboard update student data and can generate notifications or messages visible in the student area.

## 7. Inserting students into the class

Student management is available from the "Students and Teachers" > "Student List" menu, or from the `/docenti/studenti` page.

The page works on the currently selected class. If a class has not been selected, the system takes you to the `/docenti/classi` page.

### Student list

The table shows the students associated with the active class.

Fields displayed:

- surname;
- name;
- email;
- username;
- sex;
- PEI indication;
- edit button;
- delete from class button.

Students with IEPs are highlighted in the table.

### Manual entry

To insert a single student, press "Add student".

Required fields:

- "Student name";
- "Student surname";
- "Student email";
- "Student gender";
- "Student with IEP";
- "Student password".

During insertion, the username is automatically generated from the first and last name. In case of homonyms, the system generates a progressive username to avoid duplicates.

For a new student entered manually, the initial password is set to the generated username. The password field is instead useful for editing, to change the password of an existing student.

Applied controls:

- name and surname required;
- mandatory and valid email for new students;
- valid gender: `M` or `F`;
- the student must not already be present in the selected class.

### Edit student

The "Edit" button opens the student's record.

When editing you can update:

- name;
- surname;
- sex;
- PEI indication;
- password.

The email is not changed from this screen. If the password field remains blank, the current password is not changed.

### Import students from CSV

The "Import students from CSV" button allows you to upload multiple students at once.

Required format:

```text
nome;cognome;email;sesso;l104
```

The file must:

- be in `.csv` format;
- use the semicolon as separator;
- have the first header line;
- contain a maximum of 50 KB;
- indicate the sex as `M` or `F`;
- indicate `l104` with recognized values such as `1`, `true`, `si`, `sì`, `yes`, `y` or `0`/empty for negative value.

During import:

- if the student does not exist, it is created and associated with the class;
- if the student already exists as a student, he is associated with the class if he is not already present;
- if the email belongs to a teacher or administrator, the line is skipped for safety;
- a random password is generated consisting of an animal name in English and three digits;
- the system tries to send the student an email with username and password.

At the end, a summary is shown with students created, associated, already present, emails sent, emails not sent and any invalid lines.

### Import students from another class

The "Import students from another class" button allows you to associate students already present in another class with the current class.

Procedure:

- open the import window;
- select the origin class;
- confirm with "Import class".

You cannot import from the same class that is currently selected.

Imported students retain their account and data already linked, including any associated characters.

### Removing from class

The "Delete" button removes the student from the selected class.

Removing removes the connection between the student and the current class. It does not necessarily delete the student user account from the system.

## 8. Class teachers

Management of class teachers is available from the "Students and Teachers" > "Add Teachers" menu, or from the `/docenti/docenti` page.

The page works on the currently selected class. If there is no active class, the system refers to the class selection.

### Purpose of the page

This page is used to associate other teachers with the current class.

Does not create new teacher accounts. Accounts must already be registered, validated and have a teaching role.

### Teachers already associated

The first table shows the teachers already connected to the class.

Fields displayed:

- surname;
- name;
- email;
- username.

These teachers can access the class and work on the related data, according to the permissions provided by the teaching area.

### Teachers available for addition

The second table shows the validated teachers who are not yet associated with the current class.

Fields displayed:

- surname;
- name;
- email;
- username;
- "Add" button.

Pressing "Add" asks for confirmation. If confirmed, the selected teacher is associated with the current class.

### Controls applied

The system verifies that:

- the selected user exists;
- the user has a teaching role;
- the user is not already associated with the class;
- the teacher carrying out the operation has access to the selected class.

If the operation is successful, the message of the teacher successfully added to the class is shown.

## 9. Teams

Team management is available from the "Teams" side menu, or from the `/docenti/squadre` page.

The page works on the currently selected class and is used to create, check and approve student teams.

### Team list

The table shows the teams in the class, both approved and pending.

Fields displayed:

- team name;
- typology;
- creator;
- emblem;
- members and guests;
- state;
- available actions.

The state can be:

- "Approved";
- "Pending".

The waiting teams are those created by the students and not yet approved by the teacher.

### Team types

The available types are:

- Merchants;
- Magicians;
- Warriors;
- Essays.

The type is chosen during the creation or modification of the team and can be used by the system to differentiate bonuses or game behaviors. In particular, team power differs: merchants generate gold, wizards completely recharge mana, warriors completely recharge life, wise men obtain xp.

### Team creation

To create a team press "Add team".

Required fields:

- team name;
- typology;
- emblem;
- students of the team.

The emblem can be:

- uploaded as new image;
- chosen from the default emblems.

For a new team it is mandatory to select an emblem.

Each team can have a maximum of 4 students. A student already assigned to another team in the same class is not proposed as available.

The teams created by the teacher are already approved.

### Edit team

Approved teams can be edited from the "Edit" button.

You can update:

- name;
- typology;
- emblem;
- members.

For the emblem you can keep the current one, upload a new image or choose a default emblem.

### Team deletion

The "Delete" button removes an approved team.

Deletion erases:

- the team;
- connections with members;
- any related invitations.

### Approve or reject student-created teams

Students can propose the creation of a team. In this case the team appears with a "Waiting" status. The teams must be approved to avoid inappropriate names or images inserted by the students.

Available actions:

- "Approve": approve the team and send notifications to the students involved;
- "Reject": delete the proposed team and related invitations.

When a team is approved, the creator receives an approval notification and invited students are invited to join the team.

When a team is rejected, the creator receives a disapproval notification.

## 10. Quest

Quest management is available from the "Quest" side menu, or from the `/docenti/quest` page.

The quest is an educational path structured in:

- main quest;
- map of the quest;
- chapters positioned on the map;
- exercises linked to the chapters;
- student submissions and evaluations.

The page always works on the currently selected class.

### Quest list

The home page displays the list of quests available for the class.

For each quest there are:

- name;
- image;
- map access button;
- edit button;
- delete button.

The "Login" button opens the quest map, from which you can manage chapters and exercises.

### Creating or editing a quest

To create a new quest press "New quest".

Main fields:

- "Question name": name displayed to the teacher and students;
- "Quest image": representative image of the quest;
- "Quest map": image used as background map;
- "Lock exercises": how students progress.

Accepted images are in common formats, such as `jpg`, `jpeg`, `png`, `gif`, and `webp`.

The "Lock exercises" item controls the order of progress:

- if the block is active, the student must complete the previous exercises before accessing the following ones;
- if the block is not active, the active exercises are accessible without progressive constraints.

In edit it is possible to update the name, the blocking mode and, if necessary, the associated images.

### Map of the quest

When entering a quest the map is shown. The map serves to visually represent the route and position the chapters on the map.

Available actions:

- return to the list of quests;
- open the list of chapters;
- view unevaluated submissions;
- add a new chapter.

To insert a chapter:

- press "Add chapter";
- click on the map at the point where the chapter should appear;
- enter the name of the chapter;
- indicate the progressive number;
- save.

The `x` and `y` coordinates are automatically filled in based on the selected point on the map.

### Chapter list

The chapter list shows all the chapters of the quest sorted by progression.

Fields displayed:

- progressive;
- chapter name;
- available actions.

From the edit button you can update:

- chapter name;
- coordinates on the map;
- progressive.

The progressive determines the display order and, when the exercise block is active, contributes to the unlock sequence for students.

### Chapter detail and exercises

Opening a chapter displays the list of associated exercises.

For each exercise the following are visible:

- progressive;
- exercise name;
- subject;
- typology;
- expected experience points;
- activation status;
- available actions.

Inactive exercises can be modified or eliminated.

Active exercises cannot be modified or deleted from the teacher screen. For these exercises, consultation of the submissions is available.

The table highlights the active exercises:

- active exercise without pending submissions: line highlighted as active;
- active exercise with assignments to be evaluated: highlighted line to draw the teacher's attention.

### Creating an exercise

To create an exercise, enter the chapter and press the add button.

Main fields:

- exercise name;
- type of exercise;
- difficulty;
- matter;
- subject;
- related materials;
- support links;
- experience points;
- coins;
- history;
- number of questions;
- text of the exercise.

The types of exercise available are:

- open answer;
- multiple choice quizzes;
- exercise to be delivered;
- mixed quiz with multiple answers and open questions.

The difficulty can be set to increasing levels, from easy to very difficult. Difficulty is also used when calculating rewards.

The subject and the topic serve to connect the exercise to the educational contents present in the system. After choosing the topic, it is possible to associate materials already loaded for that topic. Topics and multiple choice questions can be set in the "Test creator" section

The "Support Link" field allows you to insert external references useful to the student.

The "Story" and "Exercise text" fields use an advanced text editor. The editor also allows the insertion of images and mathematical formulas in Latex format.

### Simplified text for students with IEPs

In the exercise modification there may also be a field for the simplified text.

This text is shown to students marked with IEP, if completed. If the simplified text is not present, these students also see the standard text of the exercise.

### Editing an exercise

An exercise can only be modified if it is not yet active.

In modification and possible to update:

- name;
- progressive;
- difficulty;
- related materials;
- support links;
- experience points;
- coins;
- history;
- exercise text;
- simplified text.

Subject, topic and type are bound to the structure of the exercise and are not freely modified from the editing screen.

### Activation of exercises

An exercise becomes visible to students only after activation.

When the teacher activates an exercise:

- the exercise is available in the students' quest;
- the system records the active status for the class;
- students receive a notification with the link to the exercise.

After activation, the exercise can no longer be modified or deleted, to avoid inconsistencies with assignments already open or completed.

### Student submissions

From the detail of the chapter, for an active exercise, the teacher can open the assignments page.

The page shows, for each student:

- name and surname;
- submission status;
- any evaluation already assigned;
- link to the student's submission.

If the student has not yet delivered, the line indicates that the submission is not present.

If the submission has been graded, the row shows the grade assigned.

### Evaluation of a submission

Opening a student's submission, the teacher sees:

- text of the exercise;
- student response;
- any files delivered;
- any answers to quizzes;
- comment field;
- evaluation field.

The evaluation is expressed with a score from 1 to 10.

Based on the rating, the student's level, the difficulty and the values set in the exercise, the system calculates and assigns rewards:

- experience points;
- coins;
- possible level advancement.

For very low ratings, the reward is reduced.

The submission already evaluated cannot be evaluated a second time from the same screen.

### Tip with Gemini

If the teacher has inserted a Gemini API key in his profile, in some assignments he can use the assessment suggestion button.

The function is available for assignments not yet graded and for exercises that require textual or manual correction. The suggestion does not replace the teacher's decision: the final grade must be checked and confirmed manually.

### Quiz exercises

For multiple choice exercises, the system compares the student's answers with the correct ones.

On the submission screen the teacher can see:

- selected answers;
- correct answers;
- suggested score or rating.

In mixed quizzes, the multiple choice part is calculated automatically, while the open questions remain to be checked and commented on.

### Unpriced submissions and problems

The page of unevaluated submissions is available from the quest map.

This page collects the tasks still to be corrected for the current quest.

For each row the following are indicated:

- student;
- chapter;
- exercise;
- any problem reporting;
- available actions.

The teacher can:

- open the submission to be corrected;
- mark a submission as problematic;
- add a description of the problem.

The problem report is used to keep track of submissions that require control before evaluation.

### Import and export quests

From the "Import/Export" button you can access the page dedicated to exchanging quests.

Available functions:

- export an original quest in `.zip` format;
- import a quest from `.zip` file;
- import a quest present in another class.

By original quest we mean one not imported from another class, but created manually by the teacher or imported from an external file.

During the export, an archive is generated with the structure of the quest, the chapters, the exercises and the connected resources.

When importing from file, if the quest contains arguments not present in the class or in the system, the program asks you to:

- associate the missing topic with an existing topic;
- create a new topic under a selected subject.

Importing from another class allows you to copy an already existing quest without having to rebuild it manually. The imported exercises are initially inactive in the new class.

### Operational notes

A complete quest requires at least:

- a created quest;
- a map;
- one or more chapters;
- one or more exercises;
- activation of exercises to be made available to students.

Before activating an exercise it is recommended to check the text, materials, rewards, difficulty and progressive order. After activation, the exercise enters the students' workflow and can no longer be freely edited.

## 11. Badges

The "Badge" menu contains two pages:

- "See badge", reachable from `/docenti/badge`;
- "Student Badge", reachable from `/docenti/badge/assegnati`.

Badges are awards linked to subject and topic. They serve to reward the achievement of educational objectives, defined by the minimum number of exercises and the minimum average required.

### Badges available

The `/docenti/badge` page shows the badges present in the system and allows you to create, modify, delete, import and export them.

The page works on the currently selected class, but the badges are mainly linked to subject and topic.

### Filters

The filters are available at the top:

- matter;
- subject.

The topic filter depends on the selected subject.

If the teacher has subjects associated with their account, the page offers an available subject and shows the related badges.

### Badge table

The table shows:

- name of the badge;
- subject and topic;
- description;
- image;
- minimum number of exercises;
- minimum average;
- type;
- available actions.

The genre can be:

- `U`: universal;
- `M`: male;
- `F`: female.

### Badge creation

To create a badge press "Add badge".

Required fields:

- badge name;
- matter;
- subject;
- description;
- minimum number of exercises;
- minimum average;
- type;
- image of the badge.

Main rules:

- the name is mandatory;
- the description is mandatory;
- the argument must be valid;
- the minimum number of exercises must be greater than `0`;
- the minimum average must be between `0` and `10`;
- the image is mandatory during creation;
- the permitted image formats are `png`, `jpg`, `jpeg`, `gif` and `webp`.

The badge is saved with the current teacher as the creator.

### Edit badge

A badge can only be modified by the teacher who created it.

When editing you can update:

- name;
- subject and topic;
- description;
- minimum number of exercises;
- minimum average;
- type;
- image.

If a new image is not loaded, the system keeps the one already present.

Badges created by other teachers are visible in read-only mode.

### Deletion of badge

A badge can only be deleted by the teacher who created it.

Deletion removes:

- the badge;
- the uploaded image;
- any assignments already registered to students.

Before deleting a badge it is therefore advisable to check whether it has already been obtained by any student.

### Badge import and export

The "Import/Export" button opens the window dedicated to exchanging badges.

Available functions:

- export of subject badges in `.zip` format;
- import of badges from the `.zip` archive.

Exporting requires selecting a subject. The generated file contains badge data and linked images.

Import requires a valid `.zip` archive. If the archive contains topics not present in the system, the program asks to associate the missing topics with existing topics.

Imported badges are assigned as created by the teacher performing the import.

### Student badges

The `/docenti/badge/assegnati` page shows the badges obtained by students in the selected class.

You can filter by:

- all students;
- a specific student.

For each assigned badge the following are shown:

- badge name;
- image;
- student;
- matter;
- subject;
- date of conquest;
- description.

This page is for consultation: it is not used to create badges and does not manually assign new badges.

### Operational notes

To use the badges correctly it is necessary that:

- the teacher has associated subjects;
- the topics are present and connected to the subjects;
- the badges are configured with consistent criteria;
- students carry out exercises linked to the topics of the badges.

The minimum number of exercises and the minimum average define the threshold required to obtain the badge. Too high values make the badge difficult to achieve; values that are too low make it less selective.

## 12. Powers

The "Powers" menu contains two pages:

- "See powers", reachable from `/docenti/poteri`;
- "Assigned Powers", reachable from `/docenti/poteri/assegnati`.

Powers are abilities that students can choose and use in the student area. Each power has a minimum level requirement and a mana cost.

### Powers available

The `/docenti/poteri` page shows the powers available for the selected class.

The table displays:

- name of power;
- description;
- image;
- required level;
- mana needed;
- type;
- available actions.

The type can be:

- "Fixed": global power of the system, visible but not modifiable by the teacher;
- "Class": Power created or imported for the current class.

### Creating power

To create a new power press "Add power".

Required fields:

- name power;
- description;
- level;
- mana consumed;
- image of power.

Main rules:

- the name is mandatory;
- the description is mandatory;
- the level must be greater than or equal to `0`;
- mana consumed must be greater than or equal to `1`;
- the image is mandatory during creation;
- the permitted image formats are `png`, `jpg`, `jpeg`, `gif` and `webp`.

The created power is linked to the currently selected class.

### Edit power

Only class powers can be changed.

When editing you can update:

- name;
- description;
- required level;
- mana needed;
- image.

If a new image is not loaded, the system keeps the one already present.

Fixed powers cannot be changed.

### Power deletion

Only class powers can be removed.

A power cannot be deleted if it has already been chosen by at least one student.

Fixed powers cannot be eliminated.

### Importing from other classes

The "Import from other classes" button allows you to copy a power created in another class into the current class.

The import window shows:

- name of power;
- description;
- class of origin;
- school year;
- required level;
- mana needed.

The following are not offered:

- fixed powers;
- powers of the same class;
- powers with a name already present in the current class.

The imported power is copied into the current class and can then be used by students depending on the level and mana required.

### Powers assigned to students

The `/docenti/poteri/assegnati` page shows the powers already chosen by the students in the class.

You can filter by:

- all students;
- a specific student.

For each assigned power the following are shown:

- name of power;
- image;
- student;
- required level;
- mana needed;
- description.

This page is for reference: it does not manually assign new powers to students.

### Student choice and use

Students choose powers from their area, when they have available powers to select.

The choice is allowed only if:

- the student has at least one power to choose;
- the power has not already been chosen by the student himself;
- the level required by the power does not exceed the student's level;
- the power is fixed or belongs to the selected class.

When the student uses a power:

- the system verifies that the power has been chosen by the student;
- check that the available mana is sufficient;
- subtracts the necessary mana;
- records the use of power;
- generate notifications for student and teacher.

Some powers may require you to select a companion as a target. In these cases the target must belong to the same class and be valid for that power.

### Operational notes

Before making many powers available, it is recommended to check:

- required level;
- mana cost;
- description of the effect;
- consistency with the class rules.

Levels that are too low or mana costs that are too low can make powers too easy to use. Too high levels or too high costs can make them little used by students.

## 13. Characters

Character management is available from the "Characters" side menu, or from the `/docenti/personaggi` page.

Characters are the initial avatars that students can choose from in their area. Each character defines starting values and images used in the student dashboard.

### Character list

The page shows the characters available for the selected class.

For each character the following are visible:

- name;
- initial life;
- initial mana;
- image;
- edit button.

Early life is represented with heart icons. Starting mana is represented with mana icons.

### Character creation

To create a character press "Add".

Required fields:

- character name;
- initial life;
- initial mana;
- shadow color;
- border color;
- description;
- avatars;
- avatar without background.

Main rules:

- the name is mandatory;
- initial life and initial mana must be at least `1`;
- the avatar is mandatory during creation;
- the avatar without background is optional;
- the permitted image formats are `jpg`, `jpeg`, `png`, `gif` and `webp`.

The created character is linked to the currently selected class.

### Character images

The "Avatar" field contains the main image of the character, shown in the tables and selection screens.

The "Avatar without background" field contains the image used to compose the character with customizations, equipment or graphic elements of the student dashboard.

If the character is to be used with graphic customisations, it is recommended to also upload the image without the background, so as to be able to insert the backgrounds into the character and possibly superimpose the colored hair. There are several online services that allow you to remove character backgrounds with AI for free.

### Colors

The shadow color and the border color are used for the graphic display of the character.

- "Shadow color": color used for the shadow effect around the image;
- "Border color": color of the image border.

These values do not change statistics or game rules.

### Edit character

The "Edit" button opens the selected character's sheet.

When editing you can update:

- name;
- initial life;
- initial mana;
- shadow color;
- border color;
- description;
- avatars;
- avatar without background.

If a new image is not loaded, the system keeps the one already present.

Changing the initial values affects new uses of the character. Students who have already chosen their character may have lives, mana, and progress already saved in their profile.

### Student's choice of character

The student chooses the character from their area, after selecting the class.

The choice is allowed only if:

- the student belongs to the class;
- the character belongs to the selected class;
- the student has not already chosen a character.

When the student chooses the character, the system saves the link to the character and initializes lives and mana with the values set by the teacher, if those values were not already present in the student's profile.

### Character import and export

From the "Import/Export" button you access the `/docenti/personaggi/import-export` page.

Available functions:

- export an original character of the class in `.zip` format;
- import a character from the `.zip` archive;
- import an original character from another class.

The export generates an archive with:

- character data;
- linked images;
- customizations associated with the character.

Importing from file requires a valid `.zip` archive. The imported character is linked to the current class.

Importing from another class shows the original characters available, with image, starting life and starting mana. By confirming the import, the system copies the character into the current class.

### Linked customizations

When a character is imported or exported, customizations linked to the character may also be included.

This is important because some customizations, such as hair or equipment, can be specific to a particular character.

### Operational notes

Before letting students choose characters it is recommended to check:

- number of characters available;
- balance between initial life and initial mana;
- main image quality;
- presence of the image without background, if customizations are used;
- character description.

Once students have chosen a character, any graphical changes are normally of little concern. However, changes to the initial values must be carefully evaluated, because students may already have game data saved.

## 14. Punishments

The "Punishments" menu contains two pages:

- "See punishments", reachable from `/docenti/punizioni`;
- "Punishments Assigned", reachable from `/docenti/punizioni/assegnate`.

Punishments are additional activities assigned to students, especially when a student loses all lives or instant death is applied from the teacher dashboard.

### Punishments available

The `/docenti/punizioni` page shows the punishments configured for the selected class.

The table displays:

- description;
- image;
- days for submission;
- available actions.

### Creation of punishment

To create a new punishment press "Add punishment".

Required fields:

- description of the punishment;
- days for submission;
- image of punishment.

Main rules:

- the description is mandatory;
- the days for submission must be at least `1`;
- the image is mandatory during creation;
- the permitted image formats are `png`, `jpg`, `jpeg`, `gif` and `webp`.

The punishment is linked to the currently selected class.

### Edit punishment

The "Edit" button allows you to update:

- description;
- days for submission;
- image.

If a new image is not loaded, the system keeps the one already present.

The change affects the punishment saved in the class. Before changing a punishment already used, it is advisable to check whether it has been assigned to students.

### Deletion of punishment

A punishment can only be eliminated if it belongs to the current class.

It is not possible to delete a punishment already assigned to at least one student.

When deletion is allowed, the system removes:

- punishment;
- the uploaded image linked to the punishment.

### Importing from other classes

The "Import from other classes" button allows you to copy a punishment present in another class into the current class.

The import window shows:

- description;
- image;
- days for submission;
- class of origin;
- school year.

No punishments of the same class or punishments with a description already present in the current class are proposed.

The imported punishment is copied to the current class and can be used in subsequent assignments.

### Assignment from the dashboard

Punishments are assigned from the Teacher Dashboard when a student reaches zero lives or when the "Instant Death" feature is used.

The assignment window allows three modes:

- random punishment;
- existing punishment;
- new punishment.

With random mode, the system chooses an available punishment for the class that is not already assigned to the student.

With the existing method, the teacher selects a punishment already present in the class.

With the new method, the teacher directly creates a new punishment indicating the description, days for submission and any image.

After assignment:

- the connection between student and punishment is created;
- the expiry date is calculated by adding the days for submission to the current date;
- the student receives a notification;
- student's lives are reset to maximum lives.

### Punishments awarded

The `/docenti/punizioni/assegnate` page shows the punishments assigned to students in the class.

The table displays:

- student name;
- student surname;
- description of the punishment;
- expiry date;
- days for submission;
- any file delivered.

If the student has uploaded an assignment, the teacher can download it from the dedicated button.

### Student side submission

The student sees the punishments not yet completed in their area, from the `/studenti/punizioni` page.

For each punishment the following are shown:

- description;
- image;
- expiry date;
- submission loading area.

When the student uploads a file:

- the file is saved among the punishment uploads;
- the punishment is marked as completed;
- the submission link is saved;
- the teacher receives a notification and can consult the submission from the assigned punishments page.

### Operational notes

Punishments are linked to the selected class. Before using them, it is recommended to prepare a list consistent with the class rules, avoiding ambiguous descriptions.

The number of days for submission must be chosen based on the type of activity required. Very short punishments can become difficult to manage; punishments that are too long lose their effectiveness in the game cycle.

To avoid duplicates, importing from other classes excludes punishments that already have the same description in the current class.

## 15. Customizations

Customization management is available from the "Customizations" side menu.

The menu includes several pages:

- customization management: `/docenti/personalizzazioni`;
- discount days: `/docenti/personalizzazioni/giornate-sconti`;
- student customizations: `/docenti/personalizzazioni/studenti`;
- customizations in use: `/docenti/personalizzazioni/in-uso`;
- customization set: `/docenti/personalizzazioni/set`.

Customizations are items that students can purchase or select to change the appearance of their character, background, or profile-related items.

### Types available

The types managed are:

- `Sfondo`: avatar background;
- `BigBackground`: main character background;
- `Capelli`: customization linked to the chosen character;
- `Personale`: personal image uploaded by the teacher or student;
- `Equipaggiamento`: equippable element;
- `Pet`: companion/pet that can be associated with the student.

Some types can be linked to a specific character. In particular `Capelli` and `Equipaggiamento` can be limited to one character.

### List of customizations

The `/docenti/personalizzazioni` page shows the customizations available for the selected class.

The table displays:

- name;
- typology;
- image;
- cost;
- connected character;
- edit button.

A filter by type is available.

Customizations created by students and linked to a specific student are shown read-only.

### Customization creation

To create a new customization press "Add".

Main fields:

- name;
- typology;
- cost;
- connected character;
- description;
- costume suffix;
- image.

Main rules:

- name and type are mandatory;
- the cost must be greater than or equal to `0`;
- the image is mandatory during creation;
- the permitted image formats are `jpg`, `jpeg`, `png`, `gif` and `webp`.

The image saving path depends on the type selected.

### Edit customization

When editing you can update:

- name;
- typology;
- cost;
- connected character;
- description;
- costume suffix;
- image;
- ability, if the type requires it.

If a new image is not loaded, the system keeps the one already present.

### Equipment and pets

For the `Equipaggiamento` and `Pet` types it is possible to associate skills.

Skills are chosen from a dedicated list and saved along with the customization.

The actual effects are applied on the student side when the item is equipped or activated, according to the rules provided by the system.
For example, armor can provide shields: shields are similar to hearts, they protect against loss of life and are consumed before losing hearts. Another ability can be the increase in mana, another the increase in the mana gained upon leveling up (for example from 2 to 3 mana). Pets can give you the chance to increase the drop chance of epic and legendary chests.

### Costumes

The "Add costume" button allows you to upload costume images to the costume folder.

The costume is not a normal customization that can be purchased from the shop, but a graphic asset used in the composition of the character's image.

The "costume suffix" field is used to link a customization to the correct costume file. The costumes connected to the equipment will then be loaded with the character's name as the first part and the inserted suffix as the second (including the file extension, for example .jpg or .png)

### Discount days

The `/docenti/personalizzazioni/giornate-sconti` page allows you to configure discounts applied to the student shop.

Required fields:

- discount date;
- discount percentage;
- annual recurrence;
- motivation.

Main rules:

- the date must be valid;
- the discount must be between `1` and `100`;
- the motivation is mandatory;
- if the annual recurrence is active, the discount is repeated every year on the same date.

On the same page the days already configured are listed, with the possibility of deleting them.

When a discount is active, the percentage applied is shown in the student shop and the final price of the items is recalculated.

### Customizations uploaded by students

The `/docenti/personalizzazioni/studenti` page shows personal images uploaded by students and still awaiting approval, in order to avoid inappropriate images or names.

For each request the following are visible:

- student;
- name of the customization;
- image;
- approval button;
- reject button.

If the request is approved:

- the customization moves to the approved status;
- is associated with the student;
- the student receives a notification.

If the request is rejected:

- the customization goes to the rejected state;
- the student receives a notification.

### Customizations in use

The `/docenti/personalizzazioni/in-uso` page allows you to check the personalizations owned and active for a student.

You can select a student in the class and view:

- customizations currently in use;
- personalizations possessed;
- active or inactive status.

This page is for consultation.

### Set of customizations

The `/docenti/personalizzazioni/set` page allows you to create and manage customization sets.

Types of sets available:

- `Equipaggiamento`;
- `Pet`;
- `BigBackground`;
- `Sfondo`.

To create a set indicate:

- set name;
- typology;
- color set.

After creation, the assignment button allows you to connect customizations of the same type to the set.

The page also allows:

- export a set in `.zip` format;
- import a set from the `.zip` archive.

The archive contains the set data, related customizations and necessary assets.

### Student-side store

Students purchase customizations from the `/studenti/personalizzazioni/negozio` page.

In the shop are available:

- avatar wallpapers;
- character wallpapers;
- hair compatible with the chosen character;
- pet;
- loading a personal customization.

Purchasing requires sufficient coins. If a discount day is active, the price is reduced by the configured percentage.

Uploading a personal customization by the student costs `800` coins. The uploaded file must be a valid image, with a maximum size of 5 MB. The image is resized and cropped to 1080x1080 pixels before saving.

Images uploaded by students do not become available immediately: they must be approved by the teacher.

### Use, sale and equipment on the student side

From the `/studenti/personalizzazioni` page, the student can choose which customizations they own to use for:

- background;
- character background;
- hair;
- personal image;
- pet.

The student can also sell owned customizations. The refund is partial.

From the `/studenti/personalizzazioni/equipaggiamento` page, the student can:

- purchase equipment;
- equip a possessed item;
- sell equipment.

When an item is equipped, the system applies the expected effects, such as bonuses linked to shields or other configured abilities.

### Operational notes

Before making many customizations available it is recommended to check:

- coherence between typology and image;
- cost in coins;
- any connected character;
- skills associated with pets and equipment;
- presence of sets, if objects must be grouped.

Customizations impact students' viewing experience and, for equipment and pets, can have gameplay effects. It is therefore advisable to keep prices and skills balanced with respect to the rewards obtainable in the class.

## 16. Materials

Material management is available from the "Materials" side menu, or from the `/docenti/materiali` page.

Materials are files uploaded by the teacher and linked to a topic. They can be used as support in quest exercises.

### Materials list

The page shows the materials uploaded by the current teacher.

The table displays:

- material name;
- description;
- matter;
- subject;
- available actions.

If the material has a linked file, the name is a link that opens in a new tab.

The materials are sorted by subject, topic and name.

### Available topics

In the upload form, the list of topics depends on the subjects associated with the teacher.

A teacher can upload materials only for topics belonging to their subjects.

If the teacher does not have any subjects or topics associated with him in the Test Creator section, he will not have useful elements to select in the topic field.

### Loading material

To load new material press "Load material".

Required fields:

- material name;
- subject;
- description;
- files.

Main rules:

- the name is mandatory;
- the topic is mandatory;
- the file is mandatory during creation;
- the topic must belong to a subject associated with the teacher.

The file is saved in the `public/assets/materiali` folder, inside a subfolder generated by the topic name.

### Edit material

The "Edit" button allows you to update:

- name;
- subject;
- description;
- files.

If a new file is not loaded, the system keeps the one already present.

If a new file is uploaded, the previous file is replaced and removed from the server.

### Removing material

The "Delete" button removes the material and the linked file.

Deletion is permitted only if:

- the material belongs to the current teacher;
- the material is not used in exercises.

A material cannot be deleted if it is linked:

- directly to an exercise;
- as additional material in the exercise materials table.

### Use in quests

When creating or modifying a quest exercise, the teacher can associate materials with the exercise.

The materials available depend on the topic selected for the exercise.

The student sees the linked materials on the exercise page, in the supporting materials section. Each material is shown as a pop-up link.

In addition to the files uploaded in the "Materials" section, the exercise may also contain manually inserted support links.

### Operational notes

It is recommended to assign clear names to the materials, because the name is also shown to the students.

Before deleting or replacing a file, check whether it has already been used in published or active businesses.

To keep the library tidy, it is best to load the materials already linking them to the correct topic. This simplifies selection when creating quest exercises.

## 17. Plugins

General plugin management is available from the user menu at the top right, "Plugins" item, or from the `/docenti/plugin` page.

This section describes general plugin management only. The specific functions of the individual plugins are described in the dedicated sections.

### Purpose of the page

The page allows you to:

- see the plugins available in the system;
- activate or deactivate a plugin for the selected class;
- configure any specific parameters for the class;
- install a new plugin, only if the user has an administrator role.

Management always works on the currently selected class.

### Class plugin

The plugin table shows:

- activation status for the class;
- plugin name;
- plugin code;
- version;
- description;
- JSON configuration for the class.

A plugin can be:

- active globally and can be activated for the class;
- deactivated globally and therefore cannot be activated by the class.

If a plugin is disabled globally, the activation selector for the class is not editable.

### Activate or deactivate

To activate a plugin in the class:

- select the correct class;
- open `/docenti/plugin`;
- tick the plugin in the activation column;
- save.

To deactivate it, uncheck it and save.

The activation applies only to the current class. The same plugin can be active in one class and not active in another.

### JSON configuration

Each plugin can have a class-specific configuration.

The configuration must be entered in the "Class configuration" field in JSON format.

Structure example:

```json
{
  "chiave": "valore"
}
```

The field can be left blank if the plugin does not require configuration.

Upon saving, the system checks that the JSON is valid. If the format is incorrect, the configuration is not saved.

### Plugin menu items

When a plugin is active for the class, it can add dedicated entries in the teacher and student menus.

Plugin entries are only shown if:

- the plugin is active globally;
- the plugin is active for the selected class;
- the user has access to the correct area;
- the plugin exposes a menu item for that area.

If a teacher or student tries to open a plugin page that is not active for the class, the system blocks access and redirects to the correct page.

### Installing new plugins

The installation section is only visible to administrators.

To install a new plugin you need to load a `.zip` package.

The package must contain a valid manifest, for example:

- `plugin.json`;
- `manifest.json`;
- `.chronoquest/plugin.json`.

The manifest must indicate at least:

- plugin name;
- plugin code;
- version;
- description;
- possible configuration;
- any routes, menus or events managed by the plugin.

The plugin code must contain only lowercase letters, numbers and underscores.

If the package contains setup SQL, the system only accepts `CREATE TABLE` statements for tables with names starting with `ct_plugin_`.

### Installable files

During installation, the system extracts only files allowed in the folders provided by the plugin.

Planned areas include:

- plugin PHP code;
- plugin views;
- plugin CSS and JavaScript files;
- public assets of the plugin;
- translation files;
- any package loaded.

This limitation is to prevent a plugin package from writing files to unexpected areas of the application.

### Operational notes

Before activating a plugin in a class it is recommended to check:

- that the plugin is globally active;
- that the selected class is the correct one;
- that any JSON configuration is valid;
- that interested teachers and students have access to the class.

Plugins can change system behavior, add pages, menus or manage internal events. For this reason it is preferable to activate them one class at a time and verify their functioning before using them extensively.

## 18. Test Creator: home, subjects and topics

Test Creator is the area dedicated to the preparation and management of content for tests, exercises and materials related to the subjects.

The first pages to configure are:

- Test Creator home page;
- matter;
- subjects.

### Test Creator home page

The Test Creator home page can be reached from `/testcreator/begin`.

This page shows an initial overview of the subjects assigned to the authenticated teacher.

For each assigned subject a row is shown in the table with:

- name of the subject;
- available actions.

From the home page, the teacher can remove the association with a subject using the unassignment button.

If there are no assigned subjects, the table does not contain operational elements. In this case you need to go to the subjects page and assign at least one subject to your account.

### Subjects

The subjects page can be reached from `/testcreator/materie`.

This page is used to consult the list of available subjects and choose which subjects to associate with your teacher account.

The table shows:

- name of the subject;
- status of assignment to the teacher;
- available actions.

A subject can be:

- assigned to the current teacher;
- not assigned to the current teacher.

To work on content linked to a subject, the teacher must first assign it to his or her account.

### Assignment and unassignment of subjects

To assign a subject:

- open `/testcreator/materie`;
- identify the desired subject;
- use the assignment command.

After assignment, the subject becomes available on the Test Creator home page and on subsequent pages linked to the contents.

To remove a subject from your account:

- open the Test Creator home page or the subjects page;
- use the unassign command.

Disassignment removes the connection between teacher and subject, but does not eliminate the subject from the system.

### Administrative management of subjects

The functions of creating, modifying, deleting, importing and exporting materials are reserved for the administrator.

The administrator can:

- create a new subject;
- change the name of an existing subject;
- export a subject in JSON format;
- import a subject from JSON file;
- delete a subject, if it is not linked to content that blocks its deletion.

The subject name is mandatory and cannot exceed 255 characters.

Deletion of a subject is blocked if the subject contains related topics or quizzes.

### JSON import and export

The JSON export allows you to download a subject with the linked data expected by the system.

JSON import allows you to load a subject from a compatible `.json` file.

These functions are designed to transfer or reuse structures of already prepared materials.

Before importing a file it is necessary to verify that the JSON is valid and consistent with the format expected by Test Creator.

### Topics

The topics page can be reached from `/testcreator/argomenti`.

Topics are used to divide a subject into more specific units. They are used as a reference to organize content, questions, exercises and materials.

The page shows:

- list of topics;
- subject related to each topic;
- subject filter;
- creation, modification and deletion actions, based on user permissions.

The teacher sees and manages the topics of the subjects to which he has access. The admin can see all the subjects.

### Creating and editing topics

To create a topic:

- open `/testcreator/argomenti`;
- select the subject;
- enter the name of the topic;
- save.

To edit a topic:

- identify the topic in the table;
- open the edit command;
- correct subject or name;
- save.

The topic name is required and cannot exceed 255 characters.

A non-administrator teacher can create or edit topics only in the subjects assigned to their account.

### Deleting arguments

Deleting topics is reserved for the administrator.

A topic can only be deleted if it is not connected to materials or exercises.

If the topic cannot be deleted, the system displays a message with the reason for blocking.

When a topic is deleted, questions directly linked to that topic are also removed.

### Operational notes

Before starting to create content in Test Creator it is recommended:

- check that you have assigned the correct subjects to your account;
- create or control the main topics of each subject;
- avoid duplicate or too generic names;
- use the subject filter when the list of topics becomes extensive.

The subject-topic structure is the organizational basis of the subsequent sections of Test Creator.

## 19. Test Creator: Questions

The questions section of Test Creator allows you to create, edit, import, export and organize questions related to topics.

The main page can be reached from `/testcreator/domande`.

### Choice of topic

The `/testcreator/domande` page shows the list of topics available to the teacher.

The table contains:

- topic;
- related matter;
- action to view questions.

You can filter topics by subject.

The teacher only sees the topics of the subjects assigned to their account. The administrator can access the topics of all subjects.

To open the question archive of a topic, use the view command in the corresponding line.

### List of questions of a topic

The list of questions for a topic can be reached from:

`/testcreator/domande/argomenti/{id_argomento}`

The page shows:

- text of the question;
- type of question;
- reference book;
- group number;
- available actions.

From this page the teacher can:

- return to the topic selection;
- create a new question;
- modify an existing application;
- remove a question from your archive;
- permanently delete a question, if allowed.

The questions displayed are those associated with the current teacher.

### Creating a question

To create a question:

- open the desired topic;
- press the command to add a new question;
- fill in the required fields;
- save.

Main fields:

- text of the question;
- points;
- difficulty level, from 1 to 5;
- group number: this number indicates a group of questions and is used in the random selection of questions in the creation of quizzes. Only one question from the group is randomly chosen for inclusion in the quiz, while the others are not used. Useful when you want to create multiple quizzes with a different question of the same type for each quiz;
- number of response lines;
- reference book;
- type of question;
- any answers;
- possible text of the numerical exercise. Within the numerical exercise, you can use the characters %% and ?? to insert random numbers, in order to create identical exercises, but with different numbers. Between the characters %% and ?? 2 numbers must be entered separated by commas: random numbers will be drawn between the 2 numbers. If I write, for example, %%3,7?? a random number between 3 and 7 will be inserted there, if I write %%10,20?? I will get a printout of a number between 10 and 20.

The question text and the reference book are mandatory, but you can leave the default book to none.

### Question types

The managed types are:

- open answer;
- multiple choice;
- multiple choice;
- exercise with numbers.

For open-ended questions it is necessary to indicate the number of lines available for the answer.

For multiple choice or multiple response questions you must enter at least two answers. Correct answers are indicated via the relevant selection box.

For exercises with numbers, an extended text field is used, suitable for more structured content.

### Editing a question

To edit a question:

- open the list of questions of the topic;
- select the modification command;
- update the necessary fields;
- save.

While editing, the question type is not changed. The system maintains the type chosen during creation.

When you edit a multiple choice or multiple answer question, the answers are saved based on the values in the form.

### Images in the question text

The editor allows the uploading of images linked to the question.

Formats allowed:

- `jpg`;
- `jpeg`;
- `png`;
- `gif`;
- `webp`.

The uploaded images are saved in the folder:

`public/assets/images/Questions`

This function is useful for formulas, diagrams, graphs or images necessary to understand the question.

### Removal from teacher archive

The remove command removes the connection between the teacher and the question.

The question is not necessarily deleted from the database: it is removed from the current teacher's personal archive.

This function is useful when a question has been imported or associated with the teacher but should no longer appear in his list.

### Permanent deletion

Permanent deletion removes the question from the system.

It is only allowed if:

- the question was created by the current teacher;
- the application is not associated with other teachers;
- the question is not linked to quizzes;
- the question is not related to exercises.

If one of these constraints is not respected, the system blocks the deletion and displays a message.

Permanent deletion also removes answers linked to the question.

### Importing questions from other teachers

The import page can be reached from `/testcreator/import-domande`.

From this page the teacher can:

- choose the topic;
- view questions created by other teachers on the same topic;
- import a question into your archive;
- see a preview of the answers, when available.

Importing does not create a new duplicate application. Also associate the existing question with the teacher who imports it.

Questions already present in the teacher's archive are not shown as importable.

### Importing questions from CSV

Importing from CSV is available from the `/testcreator/import-domande/csv` page or from the CSV page of a specific topic.

The file must be in `.csv` format and must not exceed approximately 500 KB.

The expected separator is the semicolon `;`.

Column structure:

```text
domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento
```

Values allowed for `tipo_domanda`:

- `risposta aperta`;
- `scelta multipla`;
- `risposta multipla`;
- `esercizio con numeri`.

Using the `meta` field:

- for open answer: number of lines;
- for multiple choice: number of the correct answer;
- for multiple choice: numbers of correct answers separated by commas;
- for exercise with numbers: text of the exercise.

If the import is started from a specific topic, the questions are imported into that topic.

If the import is started without a topic, the system uses the `argomento` column of the CSV and searches for a match between the topics accessible to the teacher.

Invalid rows are ignored. At the end the system indicates how many questions have been imported and how many rows have been discarded.

### Export questions to CSV

The export page can be reached from `/testcreator/esporta-domande`.

From this page the teacher can:

- filter topics by subject;
- select one or more topics;
- export questions in CSV format.

The exported file uses the same structure as the import:

```text
domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento
```

The export includes only the questions of the topics accessible to the teacher.

### Operational notes

Before creating or importing questions it is recommended:

- verify that the subject is assigned to the teacher;
- check that the topic is correct;
- associate the reference book;
- use clear names and texts;
- always indicate the correct answers in the choice questions;
- avoid definitive deletions if the question has already been used in quizzes or activities.

The questions created in this section can be reused in subsequent Test Creator functions and in exercises linked to the quests.

## 20. Test Creator: Quiz

The Test Creator Quiz menu allows you to create tests starting from questions already present in the teacher's archive.

The main page can be reached from `/testcreator/quiz`.

### Quiz list

The page shows the quizzes created by the authenticated teacher.

The table contains:

- name of the quiz;
- number of questions;
- matter;
- creation date;
- available actions.

Main actions:

- generate the quiz;
- edit the quiz;
- delete the quiz.

The number of questions is calculated differently depending on the type of quiz:

- for random quizzes: sum of the rules set by number and type of question;
- for non-random quizzes: number of manually selected questions.

### Creating a quiz

To create a quiz:

- open `/testcreator/quiz`;
- press the create command;
- enter the name of the quiz;
- select the subject;
- select one or more topics;
- configure the options;
- save.

The quiz name is required and cannot exceed 255 characters.

The subject must be assigned to the teacher. The topics that can be selected depend on the subject chosen.

It is mandatory to select at least one topic.

### Quiz fields and options

These fields are available in the creation or modification form:

- quiz name;
- matter;
- subjects;
- show question points;
- mix questions;
- evaluation grid;
- random questions;
- mix answers;
- rules by question type.

The evaluation rubric is optional. If selected, it is included in the quiz printout.

The "show points" option decides whether to display the score of individual questions in the printout.

The "shuffle answers" option changes the order of answers in questions with alternatives.

### Random quiz

A random quiz automatically generates questions from the selected topics.

To configure it you need to indicate one or more rules:

- type of question;
- number of questions to extract.

The type can be:

- any type;
- open answer;
- multiple choice;
- multiple choice;
- exercise with numbers.

If a question has a non-zero group number, the system considers that group in the random selection and can extract one question per group.

The extracted questions belong to the teacher's archive and to the topics selected in the quiz.

### Quiz with manual selection

If the "random questions" option is turned off, the quiz uses manual question selection.

After saving, the system opens the page:

`/testcreator/quiz/{id_quiz}/domande-selezione`

On this page the teacher can:

- see the questions available in the selected topics;
- select the questions to include;
- save the selection.

The system only accepts questions accessible to the teacher and belonging to the quiz topics.

### Editing a quiz

To edit a quiz:

- open `/testcreator/quiz`;
- choose the quiz;
- press the edit command;
- update settings;
- save.

While editing:

- the subject remains that of the quiz;
- the random or manual mode remains the one chosen during the creation phase;
- arguments, options and rules can be updated.

If the quiz is manual, you may need to double-check your question selection after editing.

### Quiz generation

The generation command opens:

`/testcreator/quiz/{id_quiz}/genera`

The page shows previews of the quiz questions.

For a random quiz, the system extracts questions according to the configured rules.

For a manual quiz, the system uses the questions saved in the manual selection.

If there are no questions available that match the quiz settings, an error message is displayed.

### Print and PDF

From the generation page the following are available:

- standard printing;
- DSA printing;
- CSV export;
- printing for co-correction.

Standard printing generates the PDF of the quiz. The PDF is generated using the header and footer set in the loaded and saved print template.

DSA printing allows you to apply specific options:

- reduction in the number of applications by 20%;
- reduction of responses to three alternatives;
- larger text;
- OpenDyslexic font, if available in the system, a particular font designed to improve the reading of people with dyslexia.

Co-correction printing requires the number of codes to be generated and produces a PDF dedicated to co-correction management.

### CSV export of the quiz

CSV export of the quiz is available from the generation page.

The exported file contains the generated or selected questions, when compatible with the export format.

Choice questions are exported with answers and correct answer.

Rows that are not compatible with the required format can be excluded from the export.

### Deleting a quiz

The delete command removes the current teacher's quiz.

Also deleted are:

- links to topics;
- rules by question type;
- any questions selected manually.

The original questions are not deleted from the teacher's archive.

### Operational notes

Before creating a quiz it is recommended:

- verify that the subject is assigned to the teacher;
- check that the topics contain sufficient questions;
- choose whether to use random or manual selection;
- set rules consistent with the available question types;
- generate a preview before printing;
- use DSA printing only when an adapted version is needed.

The quiz depends on the questions in the teacher's archive. If the archive is empty or does not contain questions for the selected topics, the generation does not produce useful results.

## 21. Test Creator: books and evaluation rubrics

The Test Creator menu also includes management of textbooks and assessment rubrics.

The books serve as a bibliographic reference for questions. The rubrics serve as attachments or evaluation criteria in the printed quizzes.

### Books

The books page can be reached from `/testcreator/libri`.

The table shows:

- title of the book;
- publishing house;
- authors;
- state;
- available actions.

The state can be:

- active;
- deactivated.

Active books can be selected in questions as a reference book.

### Creating a book

To create a book:

- open `/testcreator/libri`;
- press the command to add a book;
- fill in the required fields;
- save.

Required fields:

- title of the book;
- publishing house;
- authors.

The fields have a maximum length of 255 characters.

### Editing a book

To edit a book:

- open `/testcreator/libri`;
- select the modification command;
- update title, publishing house or authors;
- save.

The change updates the data used as reference in the questions.

### Deactivating a book

The deactivate command sets the book as inactive.

Deactivation does not delete the book from the database and does not remove links already present in the questions.

A deactivated book remains visible in the dedicated status table, but should not be used for new questions.

### Evaluation grids

The grids page can be reached from `/testcreator/griglie`.

The grids are personal to the teacher: each teacher sees and manages their own active grids.

The table shows:

- grid name;
- available actions.

Main actions:

- create a new grid;
- modify an existing grid;
- delete a grid.

### Creating a grid

To create a grid:

- open `/testcreator/griglie`;
- press the command to add a new grid;
- enter the name;
- fill in the contents of the grid;
- save.

Required fields:

- grid name;
- contents of the grid.

The grid name cannot exceed 40 characters.

The content is inserted via a text editor and can contain a descriptive or tabular structure of the evaluation.

### Editing a grid

To edit a grid:

- open `/testcreator/griglie`;
- select the modification command;
- update name or content;
- save.

Modification is permitted only to the teacher who owns the grid.

### Deleting a grid

The delete command deactivates the grid.

The grid is not physically removed from the database: it is set as inactive and no longer appears among the available grids.

### Using rubrics in quizzes

When creating or editing a quiz, the teacher can select a grading rubric.

If a grid is associated with the quiz, its contents are included in the quiz printout, inserted at the bottom, as the last element of the quiz pages.

Only the active grids of the current teacher can be selected.

### Operational notes

Before creating questions and quizzes it is recommended:

- enter or check reference books;
- avoid unnecessary duplicates in the book archive;
- deactivate books no longer used instead of modifying them improperly;
- prepare short and readable grids;
- check the print preview of the quiz when a grid is associated.

Books and rubrics do not directly create questions or quizzes, but they make content and assessment management more tidy.

## 22. Test Creator: print template

The print template page allows you to choose the graphic appearance used in the PDF printing of the quizzes.

The page can be reached from `/testcreator/template-stampa`.

### Template list

The table shows the templates available in the system.

For each template the following is shown:

- template name;
- selection status;
- selection action.

The selected template is saved on the current teacher's account and is used in subsequent printouts of the quizzes.

If the selected template is no longer available, the system uses a fallback template.

### Template selection

To select a template:

- open `/testcreator/template-stampa`;
- identify the desired template;
- press the selection control.

The chosen template is registered for the authenticated teacher.

The selection does not modify the quizzes already created: it affects the generation of the printout when the PDF is produced.

### Structure of a template

Templates are folders present in:

`public/assets/template`

Each folder represents a template.

During printing the system searches for these files in the template folder:

- `header.html`;
- `intro.html`;
- `footer.html`.

If a file is not present, that part of the printout is left blank.

The `intro.html` file is used as the initial part of the document. The quiz content is then added by the system.

### Using assets in the template

Template HTML files can use assets in the template folder, such as images or linked files.

The system normalizes asset paths during PDF generation.

In particular, references to:

- `/assets/template/{nome_template}/`;
- `./template/{nome_template}/`;
- `/css/stampa.css`;
- `../css/stampa.css`.

This way images and CSS can be resolved correctly in PDF printing.

### Loading a new template

To load a new template:

- open `/testcreator/template-stampa`;
- press the add template command;
- select a file `.zip`;
- save.

The uploaded file must be a valid ZIP.

The ZIP must contain only one root folder. The name of this folder becomes the name of the template.

While loading:

- spaces in the folder name are removed;
- any slashes `/` or `\` are removed from the name;
- the template is copied to `public/assets/template`;
- uploading is blocked if a folder with the same name already exists.

### Loading constraints

The upload is rejected if:

- no file is loaded;
- the file is not in `.zip` format;
- the ZIP cannot be extracted;
- the ZIP does not contain a single main folder;
- the folder name is invalid;
- a template with the same name already exists;
- the destination folder is not writable.

This page does not allow for the deletion of an already installed template.

### Use in quizzes

The print template is applied when generating the PDF from:

`/testcreator/quiz/{id_quiz}/stampa`

The template affects:

- header;
- introductory part;
- footer;
- any images or styles included in the template.

The content of the questions, the answers and any evaluation grid is instead generated by the system.

### Operational notes

Before loading a template it is recommended:

- verify that the ZIP contains only one folder;
- use short folder names and without spaces;
- include `header.html`, `intro.html` and `footer.html` only if necessary;
- verify that images and CSS use compatible paths;
- generate a test print after selection.

Templates only change the appearance of the PDF. The questions, answers, scores or quiz generation criteria do not change.

## 23. Test Creator: import and export questions

Test Creator allows you to import and export questions to reuse already prepared archives or share content between teachers.

The main functions are:

- import from other teachers;
- import from CSV;
- export to CSV.

### Import menu

The main import page can be reached from `/testcreator/import-domande`.

The page shows the topics available to the teacher, filtered by subject.

The import command is available for each topic.

The teacher only sees the topics of the subjects assigned to their account.

### Import from other teachers

Importing from other teachers is available from:

`/testcreator/import-domande/argomenti/{id_argomento}/altri-docenti`

The page shows questions created by other teachers for the same topic.

The table contains:

- text of the question;
- type of question;
- reference book;
- author;
- available actions.

The teacher can:

- import the application into your archive;
- view the answers, for multiple choice or multiple answer questions.

The import does not duplicate the question in the database. The system also links the existing application to the archive of the teacher who imports it.

Questions already associated with the teacher are not shown as importable.

### Import from CSV

Import from CSV can be reached from:

`/testcreator/import-domande/csv`

or, for a specific topic:

`/testcreator/import-domande/argomenti/{id_argomento}/csv`

The file must be in `.csv` format.

The maximum file size is approximately 500 KB.

The expected separator is the semicolon `;`.

### CSV import on specific topic

If the import is started from a topic's CSV page, all valid questions are imported into that topic.

In this case the `argomento` column of the CSV is not necessary to determine the destination.

### CSV import with automatic argument

If the import is started from `/testcreator/import-domande/csv`, the system uses the `argomento` column of the CSV.

The name of the topic is compared with the topics accessible to the teacher.

If no match is found, the row is ignored.

### CSV structure

The CSV format and import can be used to have an AI construct the questions, such as chatGPT or similar. Simply specify the type of questions it must generate and the format in which they should be generated and the AI will be able to create a CSV file that can be imported directly into ChronoQuest.
The planned structure is:

```text
domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento
```

The first line can contain the header.

Fields:

- `domanda`: text of the question;
- `tipo_domanda`: question type;
- `risposta_1` - `risposta_6`: available answers, used for questions of choice;
- `meta`: technical data variable based on the type of question;
- `punti`: question score;
- `argomento`: name of the destination argument, used in import without specific argument.

### Question types in the CSV

Allowed values for `tipo_domanda`:

- `risposta aperta`;
- `scelta multipla`;
- `risposta multipla`;
- `esercizio con numeri`.

If the type is not recognized, the system treats the line as an open-ended question.

### Meta field

The `meta` field changes meaning based on the type:

- open response: number of lines available for the response;
- multiple choice: number of the correct answer;
- multiple choice: numbers of correct answers separated by commas;
- exercise with numbers: text of the exercise.

For multiple choice or multiple response questions, at least two answers are required.

For multiple choice, at least one valid correct answer must be indicated.

### Default values in CSV import

When importing from CSV the system sets some values automatically:

- group number: `0`, i.e. no group;
- reference book: `1`, i.e. none;
- difficulty level: `3`, i.e. medium difficulty;
- creation date: current date;
- owner: teacher who performs the import.

The imported questions are associated with the teacher's archive.

### Rows ignored

A row is ignored if:

- it is empty;
- does not contain the text of the question;
- has less than two answers for choice questions;
- does not indicate correct answers valid for multiple choice;
- it is not possible to determine the target topic;
- an error occurs while saving.

At the end of the import the system indicates how many questions have been imported and how many rows have been ignored.

### Export to CSV

The export page can be reached from `/testcreator/esporta-domande`.

The page shows the topics accessible to the teacher, with filter by subject.

To export:

- select one or more topics;
- use the CSV export command.

You can select all filtered topics or clear the selection.

### Contents of the exported CSV

The exported CSV uses the same structure as for the import:

```text
domanda;tipo_domanda;risposta_1;risposta_2;risposta_3;risposta_4;risposta_5;risposta_6;meta;punti;argomento
```

Export only includes:

- questions belonging to the selected topics;
- questions accessible to the teacher;
- question types supported by CSV format.

For optional questions, the `meta` field contains the index of the correct answer or indexes of the correct answers.

For open questions, the `meta` field contains the number of rows.

For exercises with numbers, the `meta` field contains the text of the exercise.

### Operational notes

Before importing or exporting questions it is recommended:

- verify that the subjects are assigned to the teacher;
- check that the arguments already exist;
- use the `;` separator in the CSV;
- keep topic names consistent;
- check the correct answers before importing;
- test with a few lines before importing an extended archive.

Importing and exporting do not replace the educational review of the questions: after the import it is advisable to check the texts, answers and scores from the questions page.

## 24. Test Creator: My Classes

The "My Classes" item in the Test Creator menu refers to `/docenti/classi`.

This item does not open an internal Test Creator function, but takes you back to the basic ChronoQuest area.

From this page the teacher can:

- consult your classes;
- create or modify classes, based on permissions;
- select a class;
- return to the ordinary management of the classroom.

The function is useful when the teacher needs to exit the Test Creator flow and return to basic ChronoQuest management. Alternatively, you can click on the ChronoQuest logo, which will take you back to the teachers section.

## 25. Test Creator: teachers email

The "Teachers' email" page can be reached from `/testcreator/mail-docenti`.

This section is visible and usable only by administrators.

It is used to manage the list of enabled emails for teachers who can register on the platform.

### Email list

The table shows:

- email address;
- deletion action.

The addresses are sorted alphabetically.

### Manual addition

To add an email:

- open `/testcreator/mail-docenti`;
- press the add command;
- enter the email address;
- save.

The system:

- normalize the address to lowercase;
- verify that the format is valid;
- prevents the insertion of duplicates.

### CSV import

The administrator can import a CSV file containing email addresses.

The system reads the addresses from the file and accepts `;` or `,` separators.

Only values with valid email format are imported.

Please note: CSV import replaces the existing list. Before proceeding, it is advisable to check that the file contains all the addresses to be maintained.

### Email deletion

The delete command removes the address from the list of enabled emails.

If the address no longer exists, the system displays an error message.

### Operational notes

This section should be used to keep the list of authorized addresses updated.

Before importing a CSV it is recommended:

- check that the file contains only valid emails;
- remove empty lines or irrelevant data;
- check that the list is complete, because the import replaces the previous one.

## 26. Test Creator: Administrators

The "Administrators" page can be reached from `/testcreator/amministratori`.

This section is visible and usable only by administrators.

It is used to manage which teachers also have administrator privileges.

### List of teachers

The table shows:

- name;
- surname;
- username;
- state;
- available actions.

The state can be:

- teacher;
- administrator.

### Promotion to administrator

To assign administrator privileges:

- open `/testcreator/amministratori`;
- identify the teacher;
- use the promotion command.

The system also adds the role of administrator to the teacher.

If the teacher is already an administrator, the operation does not create duplicates.

### Removing privileges

To remove administrator privileges:

- open `/testcreator/amministratori`;
- identify the administrator user;
- use the remove privileges command.

The system removes the administrator role from the selected user.

The master administrator with user ID `1` and username `admin` cannot be removed from this page.

### Operational notes

Administrator management modifies the user's general permissions.

It is recommended to assign the administrator role only to teachers who need to manage configuration functions, such as:

- subjects;
- templates;
- enabled emails;
- other administrators;
- reserved system functions.

Removing privileges does not delete the user and does not remove the teacher role.