Request: Query Parameter for limiting options on Game Screen

[kathy-phet]

A client would like to be able to limit the options on the Game Screen because only some are relevant for younger ages. This would clearly be something that PhET-iO could do. I'm submitting this for discussion because it might be worth discussion as a feature for all educators, offered through a query parameter. I'm not sure how much effort it would be.

[jbphet]

I'm not sure how much effort it would be.

I'm interpreting this sentence and the fact that this issue was assigned to me as a request for an estimate. I'm going to assume that this feature would work like the "screens" query param, and it would be something like "gameLevels=1,2,3". The task breakdown would be something like this:

• On the master branch:
  • add the query parameter and documentation to BAAQueryParameters
  • Add error handling that limits the screens to only the ones supported or, if none are correctly specified, ignore the parameter altogether. Examples:
  • gameLevels=3,4,5 - Levels 3 and 4 would be available, the 5 would be ignored
  • gameLevels=0,1 - Level 1 would be available, 0 would be ignored
  • gameLevels=5,6 - This would be completely ignored and all levels would be available
  • gameLevels - (no screens specified) This would be completely ignored and all levels would be available
  • Configure the StartGameLevelNode to interpret the query parameter and only add buttons for the specified levels
  • Improve the auto-layout capability of StartGameLevelNode to still look reasonably good with fewer buttons
  • Test
• Propagate changes to the current release branch
• Create an RC and test ticket for QA

Note that because the current release branch is quite divergent from master, the changes will need to be manually propagated, so that step will be a little more time consuming than normal.

I would estimate 3 hours of my time to do what is listed above, with some possible additional time to deal with anything that QA reports (though I'll definitely try to be clear that they should not log anything that is already in the live sim).

Assigning back to @kathy-phet for next steps.

[kathy-phet]

@jbphet - I'm not sure you interpreted as I intended. I think the client wants to be able to use a query parameter to remove some of these game options. Say they only want the first game icon - not the other 3 - could a query parameter say ?gameType=1,2,3,4 where you could have ?gameType=1 would only have the first game icon.

[arouinfar]

I'm going to assume that this feature would work like the "screens" query param, and it would be something like "gameLevels=1,2,3".

This was also how I interpreted @kathy-phet's question, and it seems the most generalizable across all games. I don't know if it's possible, but it would be awesome if this work could be done in vegas so that all games would benefit.

I think the client wants to be able to use a query parameter to remove some of these game options. Say they only want the first game icon - not the other 3 - could a query parameter say ?gameType=1,2,3,4 where you could have ?gameType=1 would only have the first game icon.

@kathy-phet I don't follow. This game has four levels, and the client wants to choose a subset of these. This sounds exactly what @jbphet is proposing.

[jbphet]

Well, okay, now it's assigned to me and no one else, so I guess I will interpret that as meaning that I'm being called upon to drive it. I will request some time at this week's design meeting to clarify.

[jbphet]

This issue was discussed in the 1/28/2021 design meeting, and @kathy-phet agreed that the description in https://github.com/phetsims/vegas/issues/86#issuecomment-767206369 is indeed what the client is after, and also said that the request was not actually specific to Build an Atom, it was more of a general question. We looked through the code during the meeting, and there isn't a common class for presenting the level selection buttons - that functionality is replicated in several places. Therefore, there isn't a single place where this feature could be implemented. In other words, we would have to touch a lot of sims to add this feature everywhere.

We could put the query parameter into the vegas repo, since it's the one most associated with games, but then it would take some time in each sim to handle the parameter. During the discussion, we estimated it would be a ballpark of 1/2 day per sim by the time the change was made, some testing was done, a maintenance RC was created, and a QA issue was set up. We would have QA do a spot check prior to the release. @kathy-phet said that we shouldn't jump on this just yet, and perhaps it could be accomplished through utilization of our rate-based services offering.

[jbphet]

Transferred to the vegas repo, since it is a general consideration related to games.

[pixelzoom]

Note that a gameLevels query parameter was added to Equality Explorer, details in phetsims/equality-explorer#165. It's a sim-specific query parameter (in EqualityExplorerQueryParameters.js) because vegas provides no framework or support for this aspect of games. And while it would be nice to standardize on the query parameter name by putting it in initialize-globals.js, it's impossible to address validation there, because validation is also sim-specific.

[pixelzoom]

gameLevels was standardized as part of https://github.com/phetsims/number-play/issues/92 and https://github.com/phetsims/fourier-making-waves/issues/145. So this issue has been completed since 12/14/21.

Note that it's up to the sim to add the gameLevels query parameter using getGameLevelsSchema.js, and to document it where other query parameters are documented (in Teacher Tips, etc.) For example, here's the implementation in NumberPlayQueryParameters.ts:

  // Chooses the game levels that you want to appear on the 'Game' screen.
  // Note that unlike some other PhET sims, higher level numbers are not necessarily more difficult.
  // The values correspond to the games as follows:
  // 1: Counting, Level 1
  // 2: Counting, Level 2
  // 3: Subitize, Level 1
  // 4: Subitize, Level 2
  gameLevels: getGameLevelsSchema( 4 ),

Closing.