reusable components for new games

[pixelzoom]

Over in phetsims/make-a-ten#279, we noted that several newer sims (Equality Explorer, Make A Ten, Area Model, ... others?) have deviated from past game designs. This is likely due to the need for other types of games, as well as better ways of designing games in general. Equality Explorer's game (for example) is “less formal”, more open-ended, and operates differently than older games. But it has much in common with the game in Make A Ten. And Area Model is also planned to have similarities.

Three things that need to be done with respect to these new games, in this order:

(1) Specify reusable designs. Each of these games has much in common, but also significant differences. We need to identify what these games have in common, what can be reused. Designing for reuse may involve making compromises and/or design changes to existing games. And the subsequent designs will become part of the PhET designer's toolbox.

(2) Implement reusable components. So far, each sim with a newer game has implemented its own UI components. This is undesirable, especially considering PhET-iO and a11y. The designs identified in (1) will need to be implemented, reviewed and tested, as part of the vegas repository. Hopefully some of make-a-ten can be generalized and migrated to vegas (see phetsims/make-a-ten#279). These components will become part of the PhET developer's toolbox.

(3) Replace custom code with reusable components. Sims that have implemented their own components must be switched over to the new vegas components. This will ensure leverage of common code, PhET-iO and a11y.

[pixelzoom]

In phetsims/make-a-ten#279 (comment), @ariel-phet said:

@amanda-phet, since you have been part of all these designs, can you please enumerate the common UI/UX components with this all in mind. It will also be fine if migrating the common solution to Make-a-ten results in some design tweaks. Having things common is becoming more and more important especially with keyboard nav and such.

Assigning this issue to @amanda-phet.

[amanda-phet]

(1) Reusable designs
Make a Ten, Area Model, and Equality Explorer

• Status bar: with back button, Level, level description/instructions, and star accumulation; no clock (but in Area Model there certainly could be one, but definitely not an option for Make a Ten or Equality Explorer)
• Back button saves progress of level, as opposed to "start over" button that resets level. I believe the back button is also in games like Arithmetic, Expression Exchange, and Fraction Matcher.

Make a Ten and Equality Explorer

• Star "accumulation" model, where users earn 1 star per correct challenge. There is no feedback allowing "partial credit", and there is no way to show a solution. This impacts the level selection button as well.
• User hears a ding and gets some feedback that they have achieved the goal of the challenge. Make a Ten has a next button appear, Equality Explorer has a smiley face and the "new challenge" button turns into a "next challenge button."
• After 10 challenges, the user sees a reward node and is prompted with a dialog box that they can try another level or continue playing the same level.

[amanda-phet]

I wouldn't have included Area Model in the discussion because the game model is much like all other PhET games, but the status bar does break from convention a bit because it doesn't use a start over button and it displays the score in terms of stars instead of points. I can see continuing to use that score representation, especially for younger users, but that is not the same as the score display for Equality Explorer and Make a Ten.

I can also see continuing to use back buttons instead of start over buttons for games in case you want to switch between levels but don't want to lose all progress.

[pixelzoom]

The "status bars" in Make A Ten, Area Model and Equality Explorer all have significant differences, see below. Are you proposing to somehow unify/standardize them?

Make A Ten, from master:

Area Model, from design doc:

Equality Explorer, Figure 5.3 from design doc:

[amanda-phet]

I wasn't proposing anything (yet), just identifying what the games have in common.

Area Model looks like this in the latest dev version:

(@pixelzoom edit: There are 4 "Area Model" sims. This is area-model-multiplication.)

[samreid]

In the preceding status bar "3 of 6" seems unclear, may be better to specify "problem 3 of 6" or "challenge 3 of 6" so it doesn't get confused with level, score or something else.

[pixelzoom]

2/8/18 design meeting notes.
Present: @amanda-phet @kathy-phet @ariel-phet @jonathanolson @pixelzoom.

3 reusable UI components identified:

(1) "score display" - support for 3 representations:
(a) discrete stars, e.g. ":star: :star: :star:". For use with finite number of challenges.
(b) "{number} ⭐", e.g. "3 ⭐". For use with finite or infinite number of challenges. Score of zero is displayed as a grayed out star, not "0 ⭐"
(c) "Score: {number}", e.g. "Score: 3". For use with finite or infinite number of challenges.

(2) "status bar" - Back button, arbitrary text to the right of back button, "score display" on right end of bar.

(3) "level selection button" - Modify existing VEGAS/LevelSectionItemNode to display stars as "{number} ⭐" for games that don't have finite number of challenges. Uses "score display".

I'll be doing the vegas work. Using in sim will be up to developer who is responsible for the sim.

[ariel-phet]

@andrea-phet said she would be willing to tackle this.

Feel free to have an initial consultation with @pixelzoom - he will let you know what is easy, where a good starting point might be, and what might be a "can of worms"

[pixelzoom]

Score Display

Further specification of "score display":

From #59 (comment):

(1) "score display" - support for 3 representations:
(a) discrete stars, e.g. "⭐️ ⭐️ ⭐️". For use with finite number of challenges.
(b) "{number} ⭐️", e.g. "3 ⭐️". For use with finite or infinite number of challenges. Score of zero is displayed as a grayed out star, not "0 ⭐️"
(c) "Score: {number}", e.g. "Score: 3". For use with finite or infinite number of challenges.

Mockups of (a) (b) (c) respectively:

• This component will be used in "status bar" and the existing LevelSectionItemNode.
• Stars are SCENERY_PHET/StarNode.
• All text should be localized.
• Use pattern "Score: {score}" and StringUtils.fillIn
• Options to specify text font and fill
• For option (a), the number of stars can be specified via options

Open questions, @amanda-phet please specify:

• Which options need to support fractional score?
• What fraction of a point needs to be supported? 0.5? arbitrary?
• For options (b) and (c), how do you want fractional scores displayed? As a mixed fraction? As a decimal, e.g. "3.5"? If as a decimal, do you always want the same number of decimal places, e.g. "3.0" and "3.5", or "3" and "3.5"?

[pixelzoom]

Status Bar

Further specification of "status bar".

From #59 (comment):

(2) "status bar" - Back button, arbitrary text to the right of back button, "score display" on right end of bar.

• Back button is SCENERY_PHET/BackButton
• Node to right of the back button is supplied by the client. Typically text, but could be any Node. All aspects of this Node are responsibility of the client.
• Score is displayed using one of the "score display" options shown in #59 (comment). Mockups below show the 3 options
• options (not exhaustive list): x & y margins, fill color, space between back button and client-supplied message Node
• look at vegas.ScoreboardBar for inspiration, and for code to dynamically resize to the screen width
• option to keep all "status bar" components inside layoutBounds, or to have them move to left/right edges of browser window

Mockups of status bars showing "score display" options (a)(b)(c) respectively:

@amanda-phet please verify that the above is what you want.

[pixelzoom]

Level Selection Buttons

Further specification of "level section button".

From #59 (comment):

(3) "level selection button" - Modify existing VEGAS/LevelSectionItemNode to display stars as "{number} ⭐" for games that don't have finite number of challenges. Uses "score display".

Take the existing LevelSectionItemNode and modify it to use "score display" (described in #59 (comment)). We'll probably only need options (a) and (b) for "score display", but might as well also support option (c). Keep all other existing features of LevelSectionItemNode.

Mockup examples showing "score display" options:

reactant-products-and-leftovers, "Game" screen using "score display" option (a):

equality-explorer, "Solve It!" screen, from design document, using "score display" option (b). Note how zero stars is displayed.

Hypothetical example, using "score display" option (c). Again, this option is not currently needed by any sim, but since "score display" is reused here, it should be easy to add now, and more expensive to add later.

@amanda-phet please verify that the above is what you want.

[amanda-phet]

Which options need to support fractional score?

(a) and (c). (b) should only ever be an integer number of stars.

What fraction of a point needs to be supported? 0.5? arbitrary?

Likely just 0.5, but I'm not sure if you are also wondering about stars. In the case of Arithmetic the points are integers, but the stars are fractional. I think a point is 1/36th up to 1/144th of a star.

For options (b) and (c), how do you want fractional scores displayed? As a mixed fraction? As a decimal, e.g. "3.5"? If as a decimal, do you always want the same number of decimal places, e.g. "3.0" and "3.5", or "3" and "3.5"?

(b) should not have a fraction. (c) should be left to the designer. Right now we don't have a game with fractional points (I think) so I don't feel comfortable making that call. My guess is the latter, "3"and "3.5".

The level selection buttons you include in the above comment look good to me.

For (a) the number of stars is optional, right?

For (c), I wonder if the text should have an option to read "best score" or "last score" or something like that. This seems like an opportunity for a designer to be specific. Or perhaps, just leave this as "score" and we can discuss a "best score" design in the future. (@phet-steele and I have discussed this in the past and there are some ways we can probably improve the way we share best score vs. last score, and best time.)

@arouinfar feel free to chime in as another sim designer. I am not an expert on designing games!

[pixelzoom]

@amanda-phet said:

Right now we don't have a game with fractional points (I think) so I don't feel comfortable making that call.

I believe that's correct. In some games (e.g. BCE) we award 2 points for a correct answer on the first they, 1 point for a correct answer on the second try. So a perfect score is 2 * numberOfChallenges.

For (a) the number of stars is optional, right?

Correct. I've added that to #59 (comment).

[arouinfar]

@arouinfar feel free to chime in as another sim designer. I am not an expert on designing games!

Thanks @amanda-phet! Your recommendations all sound reasonable to me. I haven't designed a game, so comparably, you're definitely the expert. 😄

[pixelzoom]

Revising the Equality Explorer game design is a pre-requisite to implementing these game components. See phetsims/equality-explorer#34 (comment).

[amanda-phet]

Would it make sense to include a "refresh" button in the status bar as an option? It seems like many games have something like this. It could also just be specific to the sim if it doesn't work in the bar.

[pixelzoom]

@amanda-phet In all of the examples I've seen so far, the designer have chose to put the Refresh button with the challenge, and not in the status bar. But if you want that flexibility, please revise the specification and mockups in #59 (comment) asap.

[pixelzoom]

PhET Girl Dialog

Another component that we need to generalize and move from make-a-ten to vegas. This screen appears when you reach 10 stars in make-a-ten:

Need an option to specify which "score display" to use. ("Discrete stars" display may not make sense here. What do you think @amanda-phet?)

Client should control when this is displayed. I.e. it's not tied to reaching any specific score.

Associated artwork (.ai and .png) will need to be moved from make-a-ten to vegas.

Associated strings will need to be moved from make-a-ten to vegas.

We'll need to come up with a good descriptive name for this. make-a-ten calls it RewardDialog. Maybe something like YouDidItDialog or KeepGoingDialog or ....

[pixelzoom]

@andrea-phet and I had a Zoom call to go over the requirements, questions, etc. I recommended doing things in this order: Score Display, Status Bar, PhET Girl Dialog, Level Selection Buttons. She's going to pilot, I'll co-pilot.

@andrea-phet If you want to see how this will be eventually used in Equality Explorer, see phetsims/equality-explorer#34 and the design document.

@ariel-phet FYI, the scope has expanded a bit. We identified one additional reusable component, se #59 (comment).

[pixelzoom]

Self-assigning because I'll be involved in this and don't want to have to keep searching for the issue.

[amanda-phet]

@amanda-phet In all of the examples I've seen so far, the designer have chose to put the Refresh button with the challenge, and not in the status bar. But if you want that flexibility, please revise the specification and mockups in #59 (comment) asap.

I discussed it (I think with Kathy) and don't think we should have that option. I originally brought it up just to consider all possibilities! But I don't think it's a good place for a refresh button so we shouldn't include it at this time.

[pixelzoom]

@amanda-phet see also the question for you in #59 (comment).

Need an option to specify which "score display" to use. ("Discrete stars" display may not make sense here. What do you think @amanda-phet?)

[amanda-phet]

Need an option to specify which "score display" to use. ("Discrete stars" display may not make sense here. What do you think @amanda-phet?)

Correct. This dialog is only relevant in games where you have an infinite number of challenges, so we should only be choosing between score displays (b) and (c).

[pixelzoom]

@andrea-phet in the commit immediately above, I replaced a group of options with starNodeOption. This is a new "nested options" pattern that we're using. See phetsims/tasks#730 (comment). Let me know if you have questions about how this works, or when to use it.

[jonathanolson]

The level selection button API seems quite inconvenient for my use case (in the fractions sims):

You can see:

• The visual part of the icon can vary in width and height
• The text part should have a consistent size and offset from the top

Naively putting in things like this results in a mess, because it looks like LevelSelectionButton always forces a rescaling of its icons (and not a consistent rescaling):

So to currently get the effect desired, I'd need to:

1. Create all of the icons that I'll need for EVERY button first, since we can't use convenient AlignBox/AlignGroup patterns for construction (as LevelSelectionButton doesn't appear to support icons changing size after construction).
2. Wrap them in AlignBoxes with a group (so we have icons that are the same size).
3. Wrap the titles in AlignBoxes with a group (since having a wider label could force a different scaling)
4. Construct the passed-in icons as a composite of a "title" and an "icon"

So a few thoughts:

1. If we'll be having these titles on the icons, can we support that?
2. Have a way of not forcing auto-scaling-to-fit. Support the use case where you have different sizes of icons that should have the same scale. If you force auto-resizing, I have to trick it into thinking all of the icons are the same size.
3. [optionally] Consider properly handling icons that resize after construction (like panel/accordionbox/etc.), as it makes certain techniques for this potentially easier.

Additionally:

• The score display (with LevelSelectionButton.ScoreDisplayCreator and ScoreDisplayDiscreteStars) doesn't shrink vertically when you have a lot of stars (the vertical space looks weird):

The older Java games had this size down nicely.

[jonathanolson]

Also in the mockup: with three stars, there is no padding to the left or right between the stars and the black border. With the current implementation, how can I accomplish that, or is that not something that will be done with level selection buttons?

[pixelzoom]

@andrea-phet Since the new level-selection button is now named LevelSelectionButton, I've reverted LevelSelectionItemNodeDeprecated to LevelSelectionItemNode.

General note: Because of the way that LevelSelectionItemNodeDeprecated was initially created, the history for LevelSelectionItemNode lives with LevelSelectionButton.

[pixelzoom]

Re @jonathanolson's issues with LevelSelectionButton in #59 (comment) and #59 (comment):

• It's incredibility costly (not to mention discouraging and demotivating) to be getting this feedback after we've complete the design and implementation process. Let's discuss why this happened, so we don't repeat this mistake in the future.

• LevelSelectionButton does not significantly deviate from the behavior that has exited in this button since it was created/ported in 2014. The only thing that is new is the ability to provide a different way of displaying the score -- it was previously limited to a discrete number of stars. Not changing other behavior was a requirement.

• Adjusting the size of the background around the score display is a relatively easy change. If you're using more than 5 or 6 stars, then you're probably using the wrong score display - but that's a different issue.

• My feeling is that (like other PhET buttons) the client should be entirely responsible for the icon that appears on these buttons. If you have requirements for uniform icon size, layout, etc. you should handle that in the sim. The responsibility of these buttons is to combine icon, score display and (options) time display. They are not responsible for the specifics of the icon. If auto-resizing of icons is making this difficult, let's look at removing that.

[pixelzoom]

Re titles and icons on level-selection buttons... In Graphing Lines, I had no problem accomplishing this, see screenshot below. I didn't find it at all "inconvenient", as you've describe it.

[jonathanolson]

Re titles and icons on level-selection buttons... In Graphing Lines, I had no problem accomplishing this, see screenshot below. I didn't find it at all "inconvenient", as you've describe it.

I'm not sure how this example applies, as the images used are all the same size. If I apply a random scale to each image, I'm sure the text size and all alignment would go crazy?

Also, since there's another case where these level titles are used, isn't that an even better argument for adding common support for it?

[jonathanolson]

As a current example, just passing in a VBox with a label and the icon, the resulting label sizes are all over the place (notice how on the bottom row, every single label is at a slightly different size):

[pixelzoom]

Your "resulting label sizes are all over the place" because you're doing nothing in your client code to ensure that they meet your client's requirements. My example from Graphing Lines shows that it's possible to do that on the client side with a minimum amount of work. The fact that Graphing Lines has uniform image file sizes is irrelevant - I could have easily dealt with that.

If you want to add additional responsibilities to LevelSelectionButton, I'm happy to discuss. But it's possible (and I would argue not "inconvenient") to accomplish what you need with the current API.

[jonathanolson]

It just seems to me that auto-scaling presents problems, and having titles as a feature of this sounds useful, as it will be used by at least 2 sims.

My feeling is that (like other PhET buttons) the client should be entirely responsible for the icon that appears on these buttons.

I'm fine being responsible for the icon, but the titles don't seem like an "icon".

I guess I'm just concerned, where if I were to create the buttons myself the code would be a LOT simpler. The assumptions made for the common code don't seem well suited to the current use case.

If auto-resizing of icons is making this difficult, let's look at removing that.

Yes, that is one of my suggestions.

[pixelzoom]

4/12/18 design meeting:

Requested changes/additions (including addressing the above LevelSelectionButton concerns) appear in #66.

Items to complete for this issue are:

• Replace LevelSelectedItemNode with LevelSelectionButton in all clients (moved to replace LevelSelectionItemNode with LevelSelectionButton #68).
• Replace ProgressIndictor with ScoreDisplayStars in all clients (moved to replace ProgressIndicator with ScoreDisplayStars area-model-common#118)

[pixelzoom]

Moving sims from deprecated to new types will be tracked in #68 and phetsims/area-model-common#118.

[pixelzoom]

Work here is completed.

Code review to be done in #70