DEV Community: Alexander Martin

Alexa Presentation Language, Part 1

Alexander Martin — Sun, 14 Mar 2021 16:39:56 +0000

In the last episode of TwoVoiceDevs, Allen Firstenberg and Stuart Pocklington talked about APL. During the interview, comparisons between APL and other technologies like HTML, CSS, and JavaScript were made over and over again. Inspired by this episode, I decided to write a blog article about it.

// Detect dark theme var iframe = document.getElementById('tweet-1370151362630197249-879'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1370151362630197249&theme=dark" }

Before we start, what is APL? APL is the abbreviation of Alexa Presentation Language and at its core it consists of several parts. One part is the APL document parsing.

By the way, the source code of APL is available on Github.

So, if there is an APL document parser, there must be an APL document - so what exactly is an APL document? The official APL documentation describes the APL document like this:

"An APL document is a JSON structure that defines a template to display on the viewport. The document controls the overall structure and layout of the visual response."

So we can say an APL document is like an HTML document, and the Alexa Presentation Language is like the Hypertext Markup Language a markup language that is used to structure electronic documents that include texts, images, and other content.

Furthermore, the official documentation says:

"An APL document combines multiple parts".

Let's look at the individual parts in detail.

APL Component

"An APL component is a primitive UI element that displays on the viewport, such as a simple text box. Components are the basic building blocks for constructing a document."

We could compare an APL component to a web component. Web components are a set of functions that provide a standard component model for the web and allow encapsulation and interoperability of individual HTML elements. In the end, we can apply this description 1:1 to our APL component. By design, APL provides a set of native APL components, these include: Text, Image, Container, ScrollView and a few others, we will go into more detail later.

APL Layouts

"A layout combines components into a reusable template and gives it a name. You can then place the layout in your document by referencing its name. Referencing a name results in a more modular design that is easier to maintain."

Again, we can compare an APL layout to a web component, because there are two types. In this case, however, we're talking about a custom, reusable web component that encapsulates other web components. Which simply means that our APL layout extends the standard APL component model with custom components.

Styles

"A style assigns a name to a set of visual characteristics, such as color and font size. You can then assign the style to a component. Use styles to keep your visual design consistent."

The concept of styles can be compared to Cascading Style Sheets from the web, it provides a way to manage the look of an APL component in one central place. Additionally, as in the web context, we have the possibility to define different styles for individual states of our component. In the web we know states like "hover", "focus", "active" and so on, also these states exist in the context of APL, partly the names are exactly the same as in the case of "hover", partly they differ, in the case of "focus", we speak in the APL context of "focused".

Resource

"A resource is a named constant you can use rather than hardcoding values. For example, you could create a resource called myRed that defines a particular shade of red, and then use that resource name to specify a color for a component."

Resources, or rather constants, are commonly used in development. Constants are usually maintained in a central place, are immutable, and are available at any point in my code.

Package

"A package bundles together all of the above elements so that you can use them across multiple APL documents. You import the package into your document."

The concept of packages is not a new invention of APL. In the context of software development, there are various names for them, dependencies, packages, modules. No matter what you call them, the underlying principle is always the same. I can use packages to add functionality to my application, I can offload things to reuse them or to structure my application.

Amazon itself provides 3 such packages.

alexa-viewport-profiles

There exists a wide range of devices on the market that support APL, whether from Amazon itself or from a third-party vendor. In this package, Amazon provides resources that group the different devices by their characteristics and combine them into a viewport profile. I would highly recommend everyone to generally work with these profiles as they ensure that my APL document will look the same on all devices associated with that profile.

alexa-styles

This package provides different resources and styles to make sure my layout works for different viewports. Let's take the example of font size, on a device with a smaller screen I obviously can't use the same font size as on a device with a larger screen. The alexa-styles package provides predefined font size names (small, medium, large) that vary depending on the device. It also provides spacing, colors and other things.

alexa-layouts

We learned earlier that APL layouts complement the standard component model, as the name of the package suggests that's exactly what happens here too. Amazon provides so-called responsive templates and components with this package, ensuring that the component works accross all viewports. These responsive components include things like a header or footer, a background image, a progress bar and many more, responsive layouts include things like a page by page list or a grid list and many others.

You're probably asking yourself now, why should I break up my APL document into packages myself? There are some advantages why you should do it:

your skill will probably end up consisting of more than just one APL document, using a package you can share APL layouts, styles or anything else between these documents.
the client, in this case the device, can cache a package which means that during the lifetime of the skill session the device has to request less data
there is a response size limit, which means that the size of your skill response may not exceed a certain limit, depending on the complexity of your APL document you can reach this limit very quickly. However, you can work around this by using packages.

Okay, so at this point we have learned the parts of our APL document. Now let's dive into the components, as we said earlier. To give you a feeling for what the component does I will show some example definitions and the corresponding HTML equivalent.

The Text component

APL:

{
  "type": "Text",
  "text": "Hello world."
}

HTML:

<p>Hello world.</p>

The Image component

APL:

{
  "type": "Image",
  "source": "https://sld.tld/image.png",
  "width": 100,
  "height": 100
}

HTML:

<img src="https://sld.tld/image.png" width="100" height="100" />

The ScrollView component

APL:

{
  "type": "ScrollView",
  "height": "50px",
  "width": "100px",
  "item": {
    "type": "Image",
    "source": "https://sld.tld/image.png",
    "width": 100,
    "height": 100
  }
}

HTML:

<div style="overflow: auto; width: 100px; height: 50px;">
  <img src="https://sld.tld/image.png" width="100" height="100" />
</div>

The Container component

At this point I would like to mention that APL uses the flexbox concept.

APL:

{
  "type": "Container",
  "alignItems": "center",
  "justifyContent": "center",
  "width": "100vw",
  "height": "100vh",
  "items": [{
    "type": "Text",
    "text": "Hello world."
  }]
}

HTML:

<div style="display: flex; align-items: center; justify-content: center; width: 100vw; height: 100vh;">
  <p>Hello world.</p>
</div>

In HTML there are different types of elements, these different types also exist for APL components.
They are divided into "Base Components", "Actionable Components", "Touchable Components" and "Multi-child Components".

Let's start with the Base components.

Base components

A component is a primitive element that displays on the viewport.

Texts, images, videos are meant here. The other component types derive from the base component.

Actionable components

An actionable component can directly receive input from touch, cursor, or keyboard events.

So with the help of an Actionable component, I have the ability to respond to user input directly in my APL document. For example, I can send an entered text to my skill backend.

The EditText component

APL:

{
  "type": "EditText",
  "onFocus": [],
  "onBlur": []
}

HTML:

<input type="text" onfocus="" onblur="" />

Touchable components

A touchable component receives input from touch or pointer events and invokes handlers to support custom touch interaction behavior.

Touchable components are an extension of Actionable components. As the name implies, the Touchable component gives me access to user input that is triggered by touch, for example. I also have the ability to provide more complex interaction capabilities with my APL document.

The TouchWrapper component

APL:

{
  "type": "TouchWrapper",
  "onDown": [],
  "onUp": [],
  "onMove": [],
  "item": {
    "type": "Text",
    "text": "TouchWrapper Sample"
  }
}

HTML:

<button ontouchstart="" ontouchend="" ontouchmove="">
  <p>TouchWrapper Sample</p>
</button>

Last but not least, the Multi-child components.

Multi-child components

A multi-child component is an abstract component that arranges and displays multiple child components

Multi-child components offer the possibility of the so-called Data Array Inflation method. You are probably wondering what the Data Array Inflation method is? Using the Data Array Inflation method we have the possibility to bind an array of values to our component, in this case we can consider the child items of our component as a template, while processing our document for each item in our array the defined template will be applied. Let me try to explain with javascript and HTML what exactly happens.

APL:

{
  "type": "Container",
  "data": [{ "name": "Foo" }, { "name": "Bar" }, { "name": "Baz" }],
  "items": [{
    "type": "Text",
    "text": "I'm ${data.name} and the ${index + 1}${index == 0 ? 'st' : '${index == 2 ? 'rd' : 'nd'}'} child in the array."
  }]
}

JavaScript/HTML:

[{ name: 'Foo' }, { name: 'Bar' }, { name: 'Baz' }].reduce((items, data, index) => {
  return items.concat(`<p>I'm ${data.name} and the ${index + 1}${index == 0 ? 'st' : `${index == 2 ? `rd` : `nd`}`} child in the array.</p>`);
}, []).join('\n');

Note: this example is highly simplified and does not support the correct spelling of the numbers st, nd, rd, th.

Once we run our JavaScript snippet, we end up with the following output, the same also applies to APL.

<p>I'm Foo and the 1st child in the array.</p>
<p>I'm Bar and the 2nd child in the array.</p>
<p>I'm Baz and the 3rd child in the array.</p>

Wonder why I used the reduce and not the map function for this example? APL offers besides the Data Array Inflation method the so called Conditional Component Inflation, but what does that mean? It's very simple, I can set conditions that in the end influence which elements should be rendered and which not.

Let me demonstrate using our previous example.

APL:

{
  "type": "Container",
  "data": [{ "name": "Foo" }, { "name": "Bar" }, { "name": "Baz" }],
  "items": [{
    "when": "${data.name == 'Foo' || data.name == 'Baz'}",
    "type": "Text",
    "text": "I'm ${data.name} and the ${index + 1}${index == 0 ? 'st' : '${index == 2 ? 'rd' : 'nd'}'} child in the array."
  }]
}

JavaScript/HTML:

[{ name: 'Foo' }, { name: 'Bar' }, { name: 'Baz' }].reduce((items, data, index) => {
  if (data.name == 'Foo' || data.name == 'Baz') {
    return items.concat(`<p>I'm ${data.name} and the ${index + 1}${index == 0 ? 'st' : `${index == 2 ? `rd` : `nd`}`} child in the array.</p>`);
  }

  return items;
}, []).join('\n');

If we run our JavaScript snippet again, we get a different return value, this is because we only consider the elements in our data array that have the name "Foo" or "Baz".

<p>I'm Foo and the 1st child in the array.</p>
<p>I'm Baz and the 3rd child in the array.</p>

And this is how Conditional Component Inflation works.

I could go on for hours, but for now I would leave it at that. What do you think? Did I confuse you more with this article than you already were? Did the article help you understand APL better? Let me know, leave a Like if you want to read more articles like this. Write me on Twitter, or use the official Alexa Slack Workspace to meet me, or other Alexa/APL developers. And if you want to find out what's possible with APL, check out APL Ninja.

Learn more:

Alexa meets Retro Game: Pong

Alexander Martin — Mon, 07 Sep 2020 17:57:17 +0000

The possibilities of APL have grown steadily since its release in 2018. With version 1.4, APL is now so powerful that even highly interactive games can be implemented. Today, I will demonstrate how to implement a Pong style game.

To implement the game in APL, we need the following components:

1) a playing field
2) the interface
3) the "physics" of the game

Preparation

Before we get started, we first define some resources. Resources have the advantage that they can be referenced by different components in the document. For example, we need the width and height of the paddle or the initial position of the ball at different points during the implementation and we will make this consistent using resources.

Resources are divided into blocks - with APL version 1.4 these blocks have been expanded by numbers, booleans, gradients and easing functions. For our purposes, however, we will focus on the numbers and strings block.

The structure of the resources is kept very simple and all we need to do is provide a name and assign a value (key-value pair):

"resources": [
  {
    "numbers": {
      "matchFieldWidth": "${viewport.width}",
      "matchFieldHeight": "${viewport.height}",
      "paddleWidth": 10,
      "paddleHeight": 100,
      "ballRadius": 10,
      "wallHeight": 4,
      "netWidth": 4,
      "netHeightOutter": 30,
      "netHeightInner": 10,
      "spacingToEdge": 25,
      "playerPaddlePositionX": "@spacingToEdge",
      "cpuPaddlePositionX": "${@matchFieldWidth - @paddleWidth - @spacingToEdge}",
      "initialPlayerPaddlePositionY": "${(@matchFieldHeight - @paddleHeight) / 2}",
      "initialCpuPaddlePositionY": "${(@matchFieldHeight - @paddleHeight) / 2}",
      "initialCpuPaddleSpeed": 8,
      "initialBallVelocityX": 8,
      "initialBallVelocityY": 8,
      "initialBallSpeed": 10,
      "initialBallPositionX": "${@matchFieldWidth / 2}",
      "initialBallPositionY": "${@matchFieldHeight / 2}"
    },
    "strings": {
      "ballDirectionLeft": "LEFT",
      "ballDirectionRight": "RIGHT",
      "initialBallDirection": "@ballDirectionRight"
    }
  }
],

As you can see, a value does not always have to be defined statically: We can use "expression evaluation" to refer to already defined values within the resources or to the variables within the initial context and calculate a value dynamically at runtime.

We have now defined our dimensions, initial positions and other helpful resources, it's time for the next step.

The playing field

For our playing field we will use a vector graphic. Vector graphics have the advantage that they can easily be scaled up or down, and they also support the gesture handlers introduced in APL 1.4.

Alexa Vector Graphics, (short AVG) are standalone documents embedded within an APL document. The structure is very similar to the structure of an APL document. An AVG is defined in the APL document under the name "graphics".

We will name our graphic "Pong".

"graphics": {
  "Pong": {
    "type": "AVG",
    "version": "1.1",
    "width": "@matchFieldWidth",
    "height": "@matchFieldHeight",
    "items": []
  }
},

This is the minimal definition of an AVG document.

We use the defined resources "matchFieldWidth" and "matchFieldHeight" for the height and width of the graphic. To reference a resource, we put the @ sign in front of the name.

To display our game field on the screen we need a VectorGraphic component. The value of the source attribute corresponds to the name of the graphic.

The mainTemplate should look like this:

"mainTemplate": {
    "parameters": [
        "payload"
    ],
    "items": [{
        "type": "VectorGraphic",
        "source": "Pong",
        "width": "@matchFieldWidth",
        "height": "@matchFieldHeight"
    }]
}

It's time to fill the playing field with life. We will now define the top and bottom walls, the ball and paddles:

"graphics": {
  "Pong": {
    "type": "AVG",
    "version": "1.1",
    "width": "@matchFieldWidth",
    "height": "@matchFieldHeight",
    "items": [
      {
        "description": "top Wall",
        "type": "path",
        "fill": "#ffffff",
        "pathData": "M0,0 L${@matchFieldWidth},0 L${@matchFieldWidth},${@wallHeight} L0,${@wallHeight} Z"
      },
      {
        "type": "group",
        "description": "bottom Wall",
        "translateY": "${@matchFieldHeight - @wallHeight}",
        "items": [
          {
            "type": "path",
            "fill": "#ffffff",
            "pathData": "M0,0 L${@matchFieldWidth},0 L${@matchFieldWidth},${@wallHeight} L0,${@wallHeight} Z"
          }
        ]
      },
      {
        "type": "group",
        "description": "User paddle",
        "translateX": "@playerPaddlePositionX",
        "translateY": "@initialPlayerPaddlePositionY",
        "items": [
          {
            "type": "path",
            "fill": "#ffffff",
            "pathData": "M0,0 L${@paddleWidth},0 L${@paddleWidth},${@paddleHeight} L0,${@paddleHeight} Z"
          }
        ]
      },
      {
        "type": "group",
        "description": "CPU paddle",
        "translateX": "@cpuPaddlePositionX",
        "translateY": "@initialCpuPaddlePositionY",
        "items": [
          {
            "type": "path",
            "fill": "#ffffff",
            "pathData": "M0,0 L${@paddleWidth},0 L${@paddleWidth},${@paddleHeight} L0,${@paddleHeight} Z"
          }
        ]
      },
      {
        "type": "group",
        "description": "Ball",
        "translateX": "@initialBallPositionX",
        "translateY": "@initialBallPositionY",
        "items": [
          {
            "type": "path",
            "fill": "#ffffff",
            "pathData": "M-${@ballRadius},0a${@ballRadius},${@ballRadius} 0 1,0 ${@ballRadius * 2},0a${@ballRadius},${@ballRadius} 0 1,0 -${@ballRadius * 2},0"
          }
        ]
      }
    ]
  }
},

To be able to position a path within a vector graphic, it is necessary to enclose it with an AVG group item. As you can see, we do not use static paths, but create them dynamically at runtime using the defined resources.

There are still two elements missing, the score and the net. For the missing items we will use two new APL 1.4 features, the AVG text item and Patterns.

Let's start with our net: a naive approach would be to implement the net as a series of paths with a small distance between them. The disadvantage would be that we would have to do this for each possible viewport height separately! The new patterns in APL 1.4 offer an elegant alternative: patterns allow us to define fragments that can be reused - for example to fill another path. As mentioned above, AVGs are standalone documents and allow to define resources in the same way as the APL document. We are going to add a resources block with a pattern definition to our AVG.

"graphics": {
  "Pong": {
    "type": "AVG",
    "resources": [
      {
        "patterns": {
          "Net": {
            "width": "@netWidth",
            "height": "@netHeightOutter",
            "items": [
              {
                "type": "path",
                "fill": "#ffffff",
                "pathData": "M0,0 L${@netWidth},0 L${@netWidth},${@netHeightInner} L0,${@netHeightInner} Z"
              }
            ]
          }
        }
      }
    ],
    "version": "1.1",

The definition specifies a pattern that is 2dp wide and 30dp high, and a path that is also 2dp wide but only 10dp high.

We will now position another group for our net with a path in the middle of the screen next to our paddles and the ball.

{
  "type": "group",
  "description": "Net",
  "translateX": "${@matchFieldWidth / 2}",
  "items": [
    {
      "type": "path",
      "fill": "@Net",
      "pathData": "M0,0 L2,0 L2,${@matchFieldHeight} L0,${@matchFieldHeight} Z"
    }
  ]
},

We add the net as the first element in our items array to avoid overlapping. The structure of the group is similar to the already existing elements. The difference is that we use our pattern to fill in the path.

The last element missing is the current score display, for this we use the next feature from the APL 1.4 update - AVG text item.

{
  "type": "text",
  "description": "Player score",
  "fill": "#ffffffd9",
  "fontSize": 100,
  "fontWeight": "700",
  "text": "0",
  "x": "${@matchFieldWidth / 4}",
  "y": "${@matchFieldHeight / 5}"
},
{
  "type": "text",
  "description": "CPU score",
  "fill": "#ffffffd9",
  "fontSize": 100,
  "fontWeight": "700",
  "text": "0",
  "textAnchor": "middle",
  "x": "${3 * @matchFieldWidth / 4}",
  "y": "${@matchFieldHeight / 5}"
}

We do not need a surrounding group for the text elements since we can use the x and y property to position the items directly. For simplicity's sake, we won't define additional resources for the positions as we only need them here. We use textAnchor middle to center the text on our x and y coordinate. Without this parameter, the text might pop out of the screen in case of a larger number.

We have now created all the elements for our field, it's time to bring some action into the game.

The Interface

To be able to move the paddle of the player we will use the gesture handlers introduced with APL 1.4. Currently the handlers only work with a VectorGraphic or TouchWrapper component. For our case we need the onMove handler, but additionally we have to define the onUp and onDown handler. In the next step we add the necessary attributes to our VectorGraphic component.

{
  "type": "VectorGraphic",
  "source": "Pong",
  "width": "${@matchFieldWidth}",
  "height": "${@matchFieldHeight}",
  "onDown": [],
  "onUp": [],
  "onMove": []
}

Within the handlers we have access to detailed information such as the x and y coordinates or the dimensions of the component that triggered the event. Before we can continue with our handler, we have to define a variable to store the current position of the event.

{
  "type": "VectorGraphic",
  "source": "Pong",
  "width": "${@matchFieldWidth}",
  "height": "${@matchFieldHeight}",
  "bind": [
    {
      "name": "playerPaddlePositionY",
      "type": "number",
      "value": "@initialPlayerPaddlePositionY"
    }
  ],
  "playerPaddlePositionY": "${playerPaddlePositionY}",
  "onDown": [],
  "onUp": [],
  "onMove": []
}

We bind the variable "playerPaddlePositionY" with the initial position of our paddle to our VectorGraphic component and pass it to our graphic. It is necessary to register the variable to use it within the AVG definition. We add a parameters property, the value of the property is an array of objects or strings.

"graphics": {
  "Pong": {
    "parameters": ["playerPaddlePositionY"],
    "type": "AVG",
    "version": "1.1",
    ...

Furthermore we have to replace our resource (@initialPlayerPaddlePositionY) with the new variable (playerPaddlePaddlePositionY).

before	after
"description": "User Paddle", "translateX": "@initialPlayerPaddlePositionX", "translateY": "@initialPlayerPaddlePositionY",	"description": "User Paddle", "translateX": "@initialPlayerPaddlePositionX", "translateY": "${playerPaddlePositionY}",

We will have to change the graphic several times in the remaining steps. We have made all necessary preparations and can implement our handler logic.

"onMove": [
  {
    "type": "SetValue",
    "property": "playerPaddlePositionY",
    "value": "${Math.clamp(0, event.component.y - @paddleHeight, @matchFieldHeight)}"
  }
]

We use the SetValue command to change the value of our variable "playerPaddlePositionY". Math.clamp is another feature that was introduced with the APL update. Math.clamp is an elegant notation for "Math.min(Math.max(value, min), max)" and ensures that the paddle only moves within the playing field.

A small step is still missing to make the player's paddle move. We have to implement "onUp" and "onDown". Since there is no use case for these handlers we will use the standard command "Idle".

"onDown": [
  {
    "type": "Idle"
  }
],
"onUp": [
  {
    "type": "Idle"
  }
],

That's it, we are able to move the paddle with the gesture control.

However, how can we move the ball or the enemy's paddle? The answer is: tick handlers.

Tick handlers allow you to periodically execute commands. Before we implement the tick handler, we define all the variables we need for the final step.

"type": "VectorGraphic",
"source": "Pong",
"width": "${@matchFieldWidth}",
"height": "${@matchFieldHeight}",
"bind": [
  {
    "name": "playerPaddlePositionY",
    "type": "number",
    "value": "@initialPlayerPaddlePositionY"
  },
  {
    "name": "cpuPaddlePositionY",
    "type": "number",
    "value": "@initialCpuPaddlePositionY"
  },
  {
    "name": "cpuScore",
    "type": "number",
    "value": "0"
  },
  {
    "name": "playerScore",
    "type": "number",
    "value": "0"
  },
  {
    "name": "pointOfCollision",
    "type": "number",
    "value": "0"
  },
  {
    "name": "ballVelocityX",
    "type": "number",
    "value": "@initialBallVelocityX"
  },
  {
    "name": "ballVelocityY",
    "type": "number",
    "value": "@initialBallVelocityY"
  },
  {
    "name": "ballSpeed",
    "type": "number",
    "value": "@initialBallSpeed"
  },
  {
    "name": "ballPositionX",
    "type": "number",
    "value": "@initialBallPositionX"
  },
  {
    "name": "ballPositionY",
    "type": "number",
    "value": "@initialBallPositionY"
  },
  {
    "name": "ballDirection",
    "type": "string",
    "value": "@initialBallDirection"
  },
  {
    "name": "cpuPaddleSpeed",
    "type": "number",
    "value": "@initialCpuPaddleSpeed"
  }
],
"playerPaddlePositionY": "${playerPaddlePositionY}",

We have defined variables for the score, the position/speed of the ball, the position of the enemy paddle and many more variables. We will pass all relevant variables to our graphic.

{
  "type": "VectorGraphic",
  "source": "Pong",
  "width": "${@matchFieldWidth}",
  "height": "${@matchFieldHeight}",
  "bind": [
    {
      "name": "playerPaddlePositionY",
      "type": "number",
      "value": "@initialPlayerPaddlePositionY"
    },
    …
   {
      "name": "cpuPaddleSpeed",
      "type": "number",
      "value": "@initialCpuPaddleSpeed"
    }
  ],
  "playerPaddlePositionY": "${playerPaddlePositionY}",
  "ballPositionX": "${ballPositionX}",
  "ballPositionY": "${ballPositionY}",
  "cpuScore": "${cpuScore}",
  "playerScore": "${playerScore}",
  "cpuPaddlePositionY": "${cpuPaddlePositionY}",
  ...
}

And also register the variables as parameters.

"Pong": {
  "parameters": [
    "playerPaddlePositionY",
    "ballPositionX",
    "ballPositionY",
    "cpuScore",
    "playerScore",
    "cpuPaddlePositionY"
  ],

Furthermore we have to change some things in our graphic again, the table shows which of them:

before	after
"translateY": "@initialCpuPaddlePositionY",	"translateY": "${cpuPaddlePositionY}",
"translateX": "@initialBallPositionX", "translateY": "@initialBallPositionY",	"translateX": "${ballPositionX}", "translateY": "${ballPositionY}",
"description": "Player Score", "text": "0",	"description": "Player Score", "text": "${playerScore}",
"description": "CPU Score", "text": "0",	"description": "CPU Score", "text": "${cpuScore}",

Our graphic should remain the same. We are now ready to implement the Tick Handler.

First we extend our VectorGraphic component with the handleTick property and define a tick handler.

{
  "type": "VectorGraphic",
  "source": "Pong",
  …
  "handleTick": [{
    "minimumDelay": "${1000 / 60}",
    "commands": []
  }]
}

The minimumDelay property specifies the interval in which our commands should be executed. We want to update our field with a frame rate of 60 frames per second, we calculate this value with ${1000 / 60}, where 1000 stands for 1000 milliseconds (= 1 second) divided by the number of frames (60) per second.

Our tick handler will be a bit more complex, therefore it is recommended to consider using user-defined commands at this point.

User defined commands can be specified in the APL document in the commands section. We will call our command "UpdateCpuPaddlePosition".

{
  "type": "APL",
  "version": "1.4",
  ...
  "commands": {
    "UpdateCpuPaddlePosition": {
      "commands": []
    }
  }
  ...
}

A custom command has 2 properties, a parameters property and a commands property.

We modify our tick handler to execute our custom command.

{
  "type": "VectorGraphic",
  "source": "Pong",
  …
  "handleTick": [{
  "minimumDelay": "${1000 / 60}",
  "commands": [{
    "type": "UpdateCpuPaddlePosition"
  }]
}

We are about to implement the logic that keeps the paddle of the enemy always aligned with the height of the ball:

"UpdateCpuPaddlePosition": {
  "commands": [
    {
      "when": "${cpuPaddlePositionY > (ballPositionY - (@paddleHeight / 2))}",
      "type": "Select",
      "commands": [
        {
          "when": "${ballDirection == @ballDirectionRight}",
          "type": "SetValue",
          "property": "cpuPaddlePositionY",
          "value": "${cpuPaddlePositionY - (cpuPaddleSpeed / 1.5)}"
        }
      ],
      "otherwise": [
        {
          "type": "SetValue",
          "property": "cpuPaddlePositionY",
          "value": "${cpuPaddlePositionY - (cpuPaddleSpeed / 4)}"
        }
      ]
    },
    {
      "when": "${cpuPaddlePositionY < (ballPositionY - (@paddleHeight / 2))}",
      "type": "Select",
      "commands": [
        {
          "when": "${ballDirection == @ballDirectionRight}",
          "type": "SetValue",
          "property": "cpuPaddlePositionY",
          "value": "${cpuPaddlePositionY + (cpuPaddleSpeed / 1.5)}"
        }
      ],
      "otherwise": [
        {
          "type": "SetValue",
          "property": "cpuPaddlePositionY",
          "value": "${cpuPaddlePositionY + (cpuPaddleSpeed / 4)}"
        }
      ]
    },
    {
      "when": "${(cpuPaddlePositionY + @paddleHeight) > (@matchFieldHeight - @wallHeight)}",
      "type": "SetValue",
      "property": "cpuPaddlePositionY",
      "value": "${@matchFieldHeight - @wallHeight - @paddleHeight}"
    },
    {
      "when": "${cpuPaddlePositionY < @wallHeight}",
      "type": "SetValue",
      "property": "cpuPaddlePositionY",
      "value": "@wallHeight"
    }
  ]
}

Our UpdateCpuPaddlePosition command has 4 blocks that are executed under certain conditions. The first two blocks cause the paddle of the enemy to move up and down. With the Select command, which was introduced with APL 1.3, we achieve an if/else statement. If none of the conditions defined in the commands array have been fulfilled, the commands defined in the otherwise array will be executed.

Through the last two blocks we make sure that the paddle of the enemy always stays inside the field.

Now it’s time to get the ball rolling (literally!).

The "physics" of the game

For the final step we will need a number of additional user-defined commands. We will call these UpdateBallPosition, CheckCollision, CheckEndOfRound and ResetGame.

"commands": {
  "UpdateCpuPaddlePosition": {
    "commands": [...]
  },
  "UpdateBallPosition": {
    "commands": []
  },
  "CheckCollision": {
    "commands": []
  },
  "CheckEndOfRound": {
    "commands": []
  },
  "ResetGame": {
    "commands": []
  }
}

Aside from "ResetGame", all commands should be executed in our tick handler:

"handleTick": [
  {
    "minimumDelay": "${1000 / 60}",
    "commands": [
      {
        "type": "CheckCollision"
      },
      {
        "type": "CheckEndOfRound"
      },
      {
        "type": "UpdateBallPosition"
      },
      {
        "type": "UpdateCpuPaddlePosition"
      }
    ]
  }
]

We first implement our UpdateBallPosition command:

"UpdateBallPosition": {
  "commands": [
    {
      "type": "SetValue",
      "property": "ballPositionX",
      "value": "${ballPositionX + ballVelocityX}"
    },
    {
      "type": "SetValue",
      "property": "ballPositionY",
      "value": "${ballPositionY + ballVelocityY}"
    },
    {
      "when": "${ballPositionY - @ballRadius < @wallHeight || ballPositionY + @ballRadius > (@matchFieldHeight - @wallHeight)}",
      "description": "ball hits the wall",
      "type": "SetValue",
      "property": "ballVelocityY",
      "value": "${ballVelocityY * -1}"
    }
  ]
},

With each "tick" we update the x and y coordinates of our ball, we also check if the ball has hit the top or bottom wall, in this case we negate our Y velocity to move the ball in a different direction.

Next we implement ResetGame:

"ResetGame": {
  "commands": [
    {
      "type": "SetValue",
      "property": "ballPositionX",
      "value": "@initialBallPositionX"
    },
    {
      "type": "SetValue",
      "property": "ballPositionY",
      "value": "@initialBallPositionY"
    },
    {
      "type": "SetValue",
      "property": "ballSpeed",
      "value": "@initialBallSpeed"
    },
    {
      "type": "SetValue",
      "property": "ballVelocityY",
      "value": "@initialBallVelocityY"
    }
  ]
}

This command resets the speed, velocity and position of the ball to the initial values.

Our ball moves across the screen and also bounces off the wall, but then disappears from the screen. Therefore we will implement the CheckEndOfRound command next.

"CheckEndOfRound": {
  "commands": [
    {
      "when": "${ballPositionX - @ballRadius < 0}",
      "type": "Sequential",
      "commands": [
        {
          "type": "ResetGame"
        },
        {
          "type": "SetValue",
          "property": "cpuScore",
          "value": "${cpuScore + 1}"
        }
      ]
    },
    {
      "when": "${(ballPositionX - @ballRadius) > @matchFieldWidth}",
      "type": "Sequential",
      "commands": [
        {
          "type": "ResetGame"
        },
        {
          "type": "SetValue",
          "property": "playerScore",
          "value": "${playerScore + 1}"
        },
        {
          "type": "SetValue",
          "property": "cpuPaddleSpeed",
          "value": "${cpuPaddleSpeed + 1}"
        }
      ]
    }
  ]
},

Depending on which side the ball leaves the screen, either the player or the computer wins. In both cases our ResetGame command is executed and the winner of the round gets one point. Moreover, our enemy gets better with each game round the player wins.

It's time for the last command to complete our Pong game! The CheckCollision command ensures that our paddles are not completely useless.

"CheckCollision": {
  "parameters": [
    {
      "name": "paddlePositionX",
      "default": "${ballDirection == @ballDirectionLeft ? (@playerPaddlePositionX + @paddleWidth) : (@cpuPaddlePositionX - @paddleWidth)}"
    },
    {
      "name": "paddlePositionY",
      "default": "${ballDirection == @ballDirectionLeft ? playerPaddlePositionY : cpuPaddlePositionY}"
    },
    {
      "name": "isWithinX",
      "default": "${(ballPositionX - @ballRadius) <= paddlePositionX && ballPositionX >= (paddlePositionX - @paddleWidth)}"
    },
    {
      "name": "isWithinY",
      "default": "${ballPositionY <= (paddlePositionY + @paddleHeight) && (ballPositionY + @ballRadius) >= paddlePositionY}"
    }
  ],
  "commands": [
    {
      "when": "${isWithinX && isWithinY}",
      "type": "Sequential",
      "commands": [
        {
          "type": "SetValue",
          "property": "pointOfCollision",
          "value": "${(ballPositionY - (paddlePositionY + @paddleHeight / 2)) / (@paddleHeight / 2)}"
        },
        {
          "type": "SetValue",
          "property": "ballVelocityX",
          "value": "${((ballPositionX + @ballRadius < @matchFieldHeight / 2) ? 1 : -1) * ballSpeed * Math.cos((Math.PI / 4) * pointOfCollision)}"
        },
        {
          "type": "SetValue",
          "property": "ballVelocityY",
          "value": "${ballSpeed * Math.sin((Math.PI / 4) * pointOfCollision)}"
        },
        {
          "type": "SetValue",
          "property": "ballSpeed",
          "value": "${Math.clamp(0, ballSpeed + 1, 25)}"
        },
        {
          "type": "SetValue",
          "property": "ballDirection",
          "value": "${ballDirection == @ballDirectionRight ? @ballDirectionLeft : @ballDirectionRight}"
        }
      ]
    }
  ]
},

This command is by far the most complex compared to the others. As I mentioned before, a parameter can be defined either as a string or an object. So far we have only used strings to register our parameters, but in this case we will use an object.

The advantage is that we can define a default value. Of course, it would also be possible to specify the parameters only as string, but for this we would have to extend our tick handler and double our CheckCollision command and also pass the correct values.

Our current CheckCollision call:

{
  "type": "CheckCollision"
},

would look like this:

{
  "when": "${ballDirection == @ballDirectionRight}",
  "type": "CheckCollision",
  "paddlePositionX: "${@cpuPaddlePositionX - @paddleWidth}",
  "paddlePositionY": "${cpuPaddlePositionY}",
  "isWithinX": "${(ballPositionX - @ballRadius) <= @cpuPaddlePositionX - @paddleWidth && ballPositionX >= (@cpuPaddlePositionX - @paddleWidth - @paddleWidth)}",
  "isWithinY": "${ballPositionY <= (cpuPaddlePositionY + @paddleHeight) && (ballPositionY + @ballRadius) >= cpuPaddlePositionY}"
},
{
  "when": "${ballDirection == @ballDirectionLeft}",
  "type": "CheckCollision",
  "paddlePositionX: "${@playerPaddlePositionX - @paddleWidth}",
  "paddlePositionY": "${playerPaddlePositionY}",
  "isWithinX": "${(ballPositionX - @ballRadius) <= @playerPaddlePositionX - @paddleWidth && ballPositionX >= (@playerPaddlePositionX - @paddleWidth - @paddleWidth)}",
  "isWithinY": "${ballPositionY <= (playerPaddlePositionY + @paddleHeight) && (ballPositionY + @ballRadius) >= playerPaddlePositionY}"
}

Quite confusing, isn't it? Plus, we have so much redundant code!

Let's get back to our CheckCollision implementation. We have defined 4 parameters (paddlePositionX, paddlePositionY, isWithinX and isWithinY) which get their value from the default property.

We also execute a number of commands when the ball hits the paddle. This is ensured by the variables isWithinX and isWithinY.

We store the point where the ball hits the paddle to determine the exit angle. We also increase the speed of the ball and we use the Math.clamp function to make sure that our ball doesn't get too fast and last but not least we update the direction in which the ball flies.

We're done!

You can find the complete APL document and many more in my GitHub repository.

I hope you enjoyed the blog article. I appreciate your feedback on Twitter (@xeladotbe ) as well as interesting APL discussions in general.