From e627cbd9917e778eaade146653a0e644f814e1dc Mon Sep 17 00:00:00 2001 From: Rob Reeder <62711024+sei-rreeder@users.noreply.github.com> Date: Fri, 31 May 2024 19:04:32 +0000 Subject: [PATCH] significant revisions made to gameboard docs --- docs/gameboard/admin-clone-yaml-json.md | 6 +-- docs/gameboard/admin-feedback-form.md | 2 +- docs/gameboard/admin-observe.md | 2 +- docs/gameboard/admin-players.md | 60 ++++++++++++++----------- docs/gameboard/admin-settings.md | 46 ++++++++++--------- docs/gameboard/reports-beta.md | 4 +- mkdocs.yml | 2 +- 7 files changed, 68 insertions(+), 54 deletions(-) diff --git a/docs/gameboard/admin-clone-yaml-json.md b/docs/gameboard/admin-clone-yaml-json.md index 8365d59..300a751 100644 --- a/docs/gameboard/admin-clone-yaml-json.md +++ b/docs/gameboard/admin-clone-yaml-json.md @@ -1,7 +1,7 @@ # Clone, yaml, and json options -## Clone +**Clone:** Creates a copy of the game that replicates most of the original game. -## Yaml +**Yaml:** Copies the yaml to your clipboard. You can use it to create a new game on a different Gameboard instance if you have more than one. -## Json \ No newline at end of file +**Json:** Copies the json code to your clipboard. \ No newline at end of file diff --git a/docs/gameboard/admin-feedback-form.md b/docs/gameboard/admin-feedback-form.md index da5098f..c73d5a6 100644 --- a/docs/gameboard/admin-feedback-form.md +++ b/docs/gameboard/admin-feedback-form.md @@ -1,4 +1,4 @@ -# Feedback Feature +# Feedback Form In the Gameboard application, it is possible to create feedback forms to capture participant feedback on the game and individual challenges. Collecting and analyzing participant feedback can help you refine and improve your games and challenges. diff --git a/docs/gameboard/admin-observe.md b/docs/gameboard/admin-observe.md index dea7c08..d9436fc 100644 --- a/docs/gameboard/admin-observe.md +++ b/docs/gameboard/admin-observe.md @@ -24,7 +24,7 @@ VM name (*win10-workstation*) and player display name (*Wolverine 3*) help obse **Rank:** Sort the consoles by scoreboard rank. -You can move a row to the top and "pin" it there to keep it in place. You can pin multiple rows at the top as well. This is useful when you are interested in following a certain few teams, players, or challenges. This also useful after you have searched---you can pin results at the top where you can reference them frequently. +You can move a row to the top and "pin" it there to keep it in place. You can pin multiple rows at the top as well. This is useful when you are interested in following a certain few teams, players, or challenges. This is also useful after you have searched--you can pin results at the top where you can reference them frequently. ![observe-pin](img/observe-pin.png) diff --git a/docs/gameboard/admin-players.md b/docs/gameboard/admin-players.md index 19af0fa..9bdc2f5 100644 --- a/docs/gameboard/admin-players.md +++ b/docs/gameboard/admin-players.md @@ -1,30 +1,30 @@ You must have the Admin Role to get to the Players screen in a game. Assuming you have been granted the appropriate role in the Gameboard, select **Admin**. Hover your mouse over an active game, then click **Players**. -**Search:** The Search feature is relative to the screen you are viewing when performing the search. - -- active-only: -- complete-only: -- advanced: -- dismissed: -- comp: -- prac: -- test: -- consolidate-teams: -- time: -- rank: -- count: -- selected: -- X -- csv: -- mail: -- rerank: -- advance: - -## Player View - -### View Data - -### Player Timeline +**Search:** The Search feature is relative to the screen you are viewing when performing the search. You can apply the following filters to your search results and take action(s). + +- active-only: Players who are actively participating. +- complete-only: Players who have completed their game. +- advanced: Players who have advanced to the next round of the game. +- dismissed: Players who have *not* advanced to the next round of the game. +- comp: Players participating in *competition* mode. +- prac: Players participating in *practice* mode. +- test: +- consolidate-teams: Collapses players on the same team to a single item in the list. +- time: Orders players by time remaining in the session. +- rank: Orders players by their current score in the game. +- auto: Sets this screen to refresh once per minute. This option is automatically selected while the game's execution window is open. +- count: Number of players who meet your search and filter requirements. +- selected: Number of players who meet your search and filter requirements *and* whom you selected. +- X: Deselects all selected players. +- csv: Exports search and filter results to a CSV file. +- mail: Exports metadata about the selected players in JSON format for use with a mail app. +- rerank: Recalculates the current rank by score of all players. This is useful in cases where some manual adjustment of a player's score requires a recalculation of the overall standings. +- extend: Extends the player's session by a specified number of minutes. +- advance: Advances the player to a different game, probably a successive round. Optionally, players can be advanced with their score intact. The `advance` function is useful when your competition is set up like a tournament where players advance in progressive rounds. Players may only be advanced to games which have an execution window equal the current time or later. + +## Player Details + +### Timeline The **Player Timeline** is a visual representation of the sequence of session events distributed chronologically along a line. It shows the order and timing of game occurrences where events have dates and times. Events on the timeline are clickable and open a modal dialog showing extra information about the event. The **Gamespace On** event is not clickable. @@ -41,6 +41,14 @@ Events seen on the player timeline are: ![player timeline](img/timeline.png) +### Session Extension + +Extends the player's session by a specified duration. + +### Other tools + +The **Announcement** feature allows you to broadcast messages to just a player or team within the game. Among other uses, these could be messages regarding gameboard issues, challenge issues, and changes to scores or time. In the Announcement field, enter the content of the announcement and click Announce. + ### Manage Challenge Bonuses Users who have the `Admin` role can manually add points to a player or team score in the context of a challenge. This is useful if bonus points were earned during a challenge and needed to be added. @@ -73,7 +81,7 @@ In the Player view context menu (the "three vertical dots") you'll notice four d - **Unenroll:** If a player has registered, but has not started a session, you can *unenroll* them from the game. They will need to re-enroll to play again. - **Reset Session (Preserve Challenges):** If a player has registered, and has started playing the game (i.e., they have a game session), you can reset their session *and not* archive any challenges, started or completed. Use of this option should be limited to very specific situations like testing and QA. -- **Reset Session:** If a player has registered and has started playing the game (i.e. they have a game session), you can reset their session. This deletes any challenge data they generated while playing but, leaves enrollment and team membership intact. If they wish to play again, they'll need to start a new session. +- **Reset Session:** If a player has registered and has started playing the game (i.e. they have a game session), you can reset their session. This deletes any challenge data they generated while playing but leaves enrollment and team membership intact. If they wish to play again, they'll need to start a new session. - **Reset Session & Unenroll:** If a player has registered, and has started a session, you can *reset* their session and *unenroll* them from the game. Players will need to re-enroll to play again. Teams are essentially dissolved and will need to reform and re-enroll to play. This is the same functionality as when a player unenrolls from the game lobby or resets their session (when enabled by an admin). Players can also unenroll themselves from the game lobby or reset their session if the admin setting **Allow Reset** is set to **Allowed** for their game. For the player perspective, see: [Participating in a game](participating.md). \ No newline at end of file diff --git a/docs/gameboard/admin-settings.md b/docs/gameboard/admin-settings.md index 43d39e2..bcf2002 100644 --- a/docs/gameboard/admin-settings.md +++ b/docs/gameboard/admin-settings.md @@ -39,11 +39,11 @@ You arrive at the **Admin Game Settings** by creating a new game or by editing a **Feedback Questions:** It's possible -- but not required -- to create questions to capture participant feedback on the game and individual challenges. Create your feedback questions here using Yaml. For help with the feedback feature, see the [Feedback Form documentation](admin-feedback-form.md). -**About feedback templates:** +**About feedback templates:** This modal provides instructions for configuring questions presented to players after they complete a challenge or game. -**Paste Example Configuration:** +**Paste Example Configuration:** Pastes sample feedback configuration into the Feedback Questions field for you to modify and use for your own needs. -**Certificate Template:** +**Certificate Template:** Design a certificate template here by entering HTML into the Certificate Template field. More information on certificates can be found in the [Playing in the Gameboard](participating.md) documentation under "The Profile screen" heading. For your convenience, selecting the **i** button displays instructions for designing a certificate that can dynamically display information related to a game, such as leaderboard rankings, player scores, and other details. ## Modes @@ -81,9 +81,9 @@ These settings pertain to registration, execution, and general game and challeng **Allow Reset:** Toggle *Forbidden* or *Allowed* to permit participants to restart their game and attempt challenges again. This option is generally allowed on a "practice" game since that game is meant to help users get their bearings on how a competition works; however, you may decide players will be forbidden to reset an "official" game. -**Allow Late Starts:** +**Allow Late Starts:** Toggle *Forbidden* or *Allowed* to permit players to start within a session length of the execution period end. When toggled to allow, players whose session would end prematurely due to the execution window closing will be allowed to play; however, their session will be shortened to match the end of the game. -**Allow Public Scoreboard Access:** +**Allow Public Scoreboard Access:** Toggle *Forbidden* or *Allowed* to permit players to view the complete scoreboard after the game ends. Not that the scoreboard itself is public, but if toggled to forbid, players can't view detailed score information for competing players. ### Registration @@ -101,17 +101,13 @@ Offering a different execution period from registration period is an option. Thi ## Challenges -**Search:** Search for challenges on TopoMojo to place in the game. *Search* here is limited by *Audience* on the workspace Settings in TopoMojo. +### Search -**Edit:** Selecting a challenge from the search results adds it to the Edit icon. +Search for challenges on TopoMojo to place in the game. *Search* here is limited by *Audience* on the workspace Settings in TopoMojo. -**Map:** Here is where the visual representation of the game is arranged. Challenges are placed on the game map here. The challenges you selected appear as hotspots on the map. Drag them into position on the map. +### Edit -**Show Grid:** Each map has a grid. By selecting Show Grid, you can toggle displaying the grid. When enabled, the grid overlays the map image and makes it easier for you place your challenge hotspots. - -**Browse:** Select **Browse** to search for an image that will serve as a backdrop to your map. - -**Reset:** Removes the image from your map. Reset does not remove challenge hotspots. +Selecting a challenge from the search results adds it to the Edit icon. #### Challenge Specs @@ -121,13 +117,11 @@ Offering a different execution period from registration period is an option. Thi **Points:** Assign a point value to your challenge here. -**Solution Guide URL:** +**Solution Guide URL:** Add links to challenge solution guides here for *practice mode* challenges. When added here, the link to the solution guide is available to players in the challenge instructions. Enabling **Show Solution Guide in Competitive Mode** permits the link to a solution guide to be available to players in a *competitive* game. -**Disabled:** Check to disable this challenge in the game without deleting it. +**Disabled:** Check to disable this challenge in the game without removing it. Disabled challenges are unavailable to players, don't count toward scores, and are not deployed when an admin initiates deployment on a player’s behalf. Essentially, disabling a challenge removes the spec from the game without deleting any underlying data. -**Show Solution Guide in Competitive Mode:** - -**Hidden:** +**Hidden:** Hidden challenges can't be manually deployed by players and don't count toward scores. However, they are deployed when an admin initiates deployment on a player's behalf or if the game configured in External mode. The need for a hidden challenge is typically related to the implementation details of an externally hosted game and is not useful for the vast majority of games. **Remove This Challenge:** Removes the challenge from the game. @@ -137,6 +131,18 @@ Prerequisites are for challenges that unlock other challenges. For example: Your ##### Automatic Bonuses -**Paste this example configuration:** +Gameboard can automatically award bonus points to teams and players based on the order in which they solve a challenge. For instance, the first team to solve a challenge can earn an extra 100 points, the second team 50 points, and so on. To configure this, use the YAML format specified below. + +**Paste this example configuration:** Click to paste the "hint" text contained in the textbox. This is a useful starting point for creating your own bonus structure YAML configuration. + +**Import this configuration:** When you have finished editing your YAML, click to commit it to Gameboard. + +### Map + +Here is where the visual representation of the game is arranged. Challenges are placed on the game map here. The challenges you selected appear as hotspots on the map. Drag them into position on the map. + +**Show Grid:** Each map has a grid. By selecting Show Grid, you can toggle displaying the grid. When enabled, the grid overlays the map image and makes it easier for you place your challenge hotspots. + +**Browse:** Select **Browse** to search for an image that will serve as a backdrop to your map. -**Import this configuration:** \ No newline at end of file +**Reset:** Removes the image from your map. Reset does not remove challenge hotspots. \ No newline at end of file diff --git a/docs/gameboard/reports-beta.md b/docs/gameboard/reports-beta.md index 2cebde9..ee3a966 100644 --- a/docs/gameboard/reports-beta.md +++ b/docs/gameboard/reports-beta.md @@ -17,7 +17,7 @@ The legacy reporting functionality has not yet been deprecated; these reports ar Each report shares common characteristics. -- **Filter controls:** Dedicated filter controls allow users to narrow down or restrict the data displayed on a report. For example, if you're interested in seeing enrollments from a given sponsor in the Enrollment Report, use the **Sponsors** filter to select the sponsor(s) you're interested in. If you don't select any values in a filter, all data from that filter included in the results. +- **Filter controls:** Dedicated filter controls allow users to narrow down or restrict the data displayed on a report. For example, if you're interested in seeing enrollments from a given sponsor in the Enrollment Report, use the **Sponsors** filter to select the sponsor(s) you're interested in. If you don't select any values in a filter, all data from that filter is included in the results. - **Copy link to report:** When a report is run, the browser generates a link that represents filter selections for the current report. Select the **clipboard icon** to copy the current report and share it with another Gameboard user. The user whom you are sharing with must have the appropriate Gameboard role and must be logged into Gameboard. You can also copy the link in your browser's address bar and share. !!! tip @@ -66,7 +66,7 @@ The screen print below shows a summary of a typical game. The summary shows: 3. 25 different sponsors participated in this example game. -Screen print 3: Sample Enrollment report +*Screen print 3: Sample Enrollment report* ![sample enrollment](img/sample-enroll-report.png) diff --git a/mkdocs.yml b/mkdocs.yml index 766b6c4..5b246e1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -83,7 +83,7 @@ nav: - Settings: gameboard/admin-settings.md - Feedback form: gameboard/admin-feedback-form.md - Completion Certificates: gameboard/completion-certificates.md - - Clone, yaml, json, Delete: gameboard/admin-clone-yaml-json.md + - Clone, yaml, and json options: gameboard/admin-clone-yaml-json.md - Cubespace Instructor Guide: - Cubespace Getting Started: cubespace-instructor/0-ins-getting-started.md - The Dauntless Manual: cubespace-instructor/ins-dauntless-manual.md