Card memory or actor memory?

State can be stored in two places: actor memory or card memory. Actor memory is state that the actor as a whole remembers; card memory is state for a specific instance of a card.

You will normally want to store your state in card memory, since that means your variables won’t get overwritten by other cards. If, however, you do want to share variables with other cards, you can use actor memory.

Card memory is accessible through the card global, like this:

  export function onCollision() {
    // Only log this message once.
    if (!card.saidHi) {
      card.saidHi = true;
      log("Hi!");
    }
  }

  export function onInit() {
    card.saidHi = false;
  }
  

The code above uses card memory to store a saidHi boolean to indicate whether or not we already printed “Hi!” to the console. Note that it resets it on onInit() too.

Initializing

You should always initialize any variables in card or actor memory before using them. The best place to do this is the onInit function.

The onInit function gets called on game reset, and also when your card has just been added to an actor.

  export function onCollide() {
    // Increment a variable.
    card.hitCount++;
  }

  export function onInit() {
    // Reset variable.
    card.hitCount = 0;
  }
  

Note: if you want to do something only when the game is reset but not when the card is added, use onResetGame instead.

Creating UI

APIv2 introduces the ability to do basic screen-space UI.

The UI is drawn in “immediate mode” meaning that the UI elements don’t have a permanent existence: they must be drawn on every tick.

Here is an example:

  // Always use onLocalTick() for UI instead of onTick():
  export function onLocalTick() {
    // Show the text "Hello world" at position 200,200:
    uiText(200, 200, "Hello world!");
  }
  

A caveat is that in a multiplayer game UI code executes on everybody’s machines, so you will draw the UI on everybody’s screen. The onLocalTick function executes locally on each machine, so the UI you draw there will draw for everybody, which is normally what you want.

The coordinate system is based on a 1600×900 “virtual screen” that is overlaid on top of the user’s screen. So coordinate (800,450) will always be the center of the screen, regardless of the actual resolution.

For more information, see uiText and uiRect.html.

Creating an Action card

So you want to create a new Action card that’s compatible with the panel system? It’s super easy. To do that, click any Action deck property (say, the “What do I do when I see the player” panel on a slime), which will create a new action card

Now, the only function you have to fill in is the onAction function, which gets called when the card is activated. Try this:

  export function onAction() {
    setTintHex("#0000ff"); // blue
  }

  export function onInit() {
    setTintHex("#00ff00"); // green
  }
  

Now give your card a name (click on the card picture on the left to edit the name and description). Suggested name: Turn Blue. Suggested description: “Makes the actor turn blue”.

Now stand in front of the slime, and it will turn blue. Reset the game and it will be green again.

If you save that card to the library, you can now use it on other objects too, wherever you’d normally use an action card.

Testing multiplayer games in single-player

If you are building a multiplayer game and you want to test it in single-player mode, you can use the console commands vpjoin, vpswitch and vpleave to simulate joining, switching or leaving your game.

1. Bring up the console using the tilde (~) key.
2. Type vpjoin. This will “join” the game as a second player.
3. To switch between players 1 and 2 you can now type vpswitch 1 and vpswitch 2.
4. Need more players? Use vpjoin again to add more!
5. To test what happens if the player leaves, use vpleave.

How can I make all players be copies of the same template?

Tired of editing each of the players in a multiplayer game? You can make them all copies of the same template.

1. Delete players 2, 3, 4, etc. Leave just player 1 (you).
2. Go into the Player Controls panel for player 1.
3. Enable Auto Assign and Auto Color.
4. Now copy and paste Player 1 as many times as you want players (so make 3 copies for a 4-player game).
5. Done! Now when someone joins your game they will inhabit one of those copies. Since they are copies, every change you make to Player 1 will auto propagate to the others.

How do I transfer the player between actors?

There is a new card called Transfer Player that you can use to transfer the player from one actor to another. For example, you could have a robot and a fox on your game and add an IF-THEN panel to the player saying that if the player presses Q, they switch from being the robot to being the fox.

1. Set the Robot to be Player 1
2. Set the Fox to be Player 2
3. Add an IF-THEN panel to the Robot
4. In the IF part add the Player Button card and set it to the desired button/key, for example Q
5. In the THEN part add the Transfer Player card and set up its parameters to point to the fox.

Now if you press Q you should switch to the fox.

If you want to add a way to switch back, just add a similar IF-THEN to the fox.