Cards 2.0 pre-release - discussion and playtest

[jon-heard]

I have pending changes to the cards system that, while definite improvements, will breaking existing design and require a new tutorial video.
I'm making this discussion for pre-release of the next iteration of the cards system. After some playtesting, it'll become the new version of Cards.
I'll maintain the original cards system (with bug fixes and non-breaking suggestions) until this one is released.

How to setup pre-release for playtesting it

1. Click on the "Import full library" button.
2. Under "What path should the library be placed in", enter "customLibSrc" (case doesn't matter). Hit "Ok".
3. Under "What is the library source", keep what's already entered, except for the end. Replace "main" with "cards2" at the end. Hit "Ok".
4. Go through the rest of the import process as normal

Once the custom library is imported, you can start playtesting it. The shortcut list below is complete, and can help if you get stuck. I'll try to answer questions quickly.
Note - Don't use cards_ui for now (the shortcuts that start with "ui cards"). I'll update them when playtesting is over.

Open discussions

• Does the order of parameters for draw and pick work?
• Does an undo feature seem useful?

Breaking changes coming in the new release

• Piles must be explicitly created before being used.
• Card facing (face-up or face-down) is per-pile, not per-card.
• No special card-pile (i.e. {table}).
  • If the either card-pile parameter is omitted from the draw or pick shortcuts, then the prior value will be used for the parameter.
  • Cards are printed to the note when moved if the pile's {show moved} flag is set.
    • This is simpler to understand than a special pile, especially now that piles must be explicitly created before being used.

All cards shortcuts

• cards reset - Clears all card-piles.
• cards settings {size: >0, default: ""} {back-image: path text, default: ""} - Updates the settings for the cards system.
  • {size} - The width for all cards, in pixels. Card height scales to match.
  • {back-image} - The path to an image file to represent face-down cards, or "default" to reset to the default back-image.

---

• cards pile {pile id: name text} {facing: up OR down, default: down} {show moved: y OR n, default: prior} - Creates an empty card-pile {pile id} with all cards facing {facing} (face-up or face-down). If {show moved}, cards that are drawn or picked into the {pile id} card-pile are also printed to the note.
• cards remove {pile id: name text} {recall: y OR n, default: n} - Removes the {pile id} card-pile, including all cards within it. If {recall}, all cards in {pile id} are recalled before the {pile id} card-pile is removed. If the {pile id} card-pile is the origin for any cards, then they are orphaned, and immediately re-origined to their current card-pile.
• cards pilesettings {pile id: name text} {facing: up OR down, default: current} {show moved: y OR n, default: current} - Updates the settings for the {pile id} card-pile.
  • {facing} - Are the {pile id} card-pile's cards shown face-up or face-down?
  • {show moved} - Are cards that are drawn or picked into the {pile id} card-pile also printed to the note?

---

• cards fromfolder {pile id: name text} {folder: path text} - Creates cards based on images in {folder} and puts them into the {pile id} card-pile.
  • Note that this does not randomize the new cards. Call cards shuffle after this to do that.

---

• cards list - Lists all card-piles.
• cards peek {count: >0 OR "all", default: 1} {pile id: name text, default: prior} {from the bottom: y OR n, default: prior OR n} - Displays the first {count} cards in the {pile id} card-pile, or ALL cards if {count} is "all". If {from the bottom}, displays the LAST {count} cards instead.

---

• cards draw {count: >0 OR "all", default: 1} {destination pile id: name text, default: prior} {source pile id: name text, default: prior} - Removes {count} cards from the {source pile id} card-pile and adds them to the {destination pile id} card-pile.
• cards pick {destination pile id: name text, default: prior} {source pile id: name text, default: prior} - Has the user choose cards from the {source pile id} card-pile. Moves the chosen cards into the {destination pile id} card-pile.

---

• cards shuffle {pile id: name text} {rotate: y OR n, default: n} - Randomizes the card order for the {pile id}. If {rotate}, then card rotations are also randomized.
  • Rotation typically means 0 or 180 degrees (right-side-up or up-side-down), but can also mean 90 or 270 degrees if the card is square.
• cards unrotate {pile id: name text} - Sets the rotation for all cards in the {pile id} card-pile to 0 (right-side-up).
• cards reverse {pile id: name text} - Reverses the order of the cards in the {pile id} card-pile.
• cards recall {pile id: name text} - Moves all cards that have the {pile id} card-pile as their origin, from their current card-piles back into the {pile id} card-pile. If {facing} is specified, all cards in {pile id} are then put to face {facing}.
• cards reorigin {pile id: name text} - Sets the origin of all cards in the {pile id} card-pile to {pile id}.

---

• cards import {pile id: name text, default: table} {data: text} - Imports the {data} into the {pile id} card pile.
• cards export {pile id: name text} - Expands to a data string containing all date for the {pile id} card-pile.

Other things (for the video, and just to do)

• Card viewer - Drag cards to reorder them.
• Card viewer - Double-tap cards to change their rotation.
• state.backgroundImage defaults to null, at which point the generic backgroundimage is used (don't put generic into state. It's big!)

[jon-heard]

The order of parameters for "cards draw" and "cards pick" is strange at first glance. It's ordered by how likely you'll need to edit each value. This way you can rely on prior entries the most, for instance if you only ever draw cards from one pile, you only have to enter the source pile the first time you draw, then leave it blank on subsequent draws. It takes some getting used to, but hopefully it's convenience outweighs its awkwardness.

[jon-heard]

I'm thinking about adding an undo feature, and maybe redo too. Does it seem like it'd be useful?

[alierecast]

I don't feel strongly one way or the other about this. Undo/redo is pretty standard stuff for card handling, but I also don't see a personal use case for myself. If it's easy to implement sure, else I might put it on the todo list as low priority?

[jon-heard]

The pre-release version is ready to play-test for anyone interested in trying it out. I've added instructions in the original post for getting the pre-release. I haven't made a tutorial video for the system, since I'm expecting changes from feedback, but I'll endeavor to answer any questions quickly.