Pong Game NMI Component (libpong)

This document describes the Pong Game NMI Component (libpong). Libpong is an implementation of the pong game where each of two players must hit a ping-pong ball with a racquet. Libpong is derived from and conforms to the Network Model Interface. This edition documents version 1.0.

1. Notices
2. Introduction
3. Installation
4. Overview
5. The Pongnmi Class
6. The Pintnmi Class
7. Examples

 -- The Detailed Node Listing ---

Introduction

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building

Overview

4.1 Movements
4.2 Rewards and Scoring
4.3 Coordinate Systems
4.4 Channel Definitions

The Pongnmi Class

5.1 Pongnmi Configuration
5.2 Pongnmi Commands
5.3 Pongnmi Input Channels
5.4 Pongnmi Output Channels

The Pintnmi Class

6.1 Pintnmi Configuration
6.2 Pintnmi Commands
6.3 Pintnmi Input Channels
6.4 Pintnmi Output Channels

1. Notices

The Pong Game NMI Component (libpong)

Copyright (C) 2003 Mike Arnold, Altjira Software, Michele Bezzi, Sony CSL.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

This software and documentation is provided "as is" without express or implied warranty. All questions should be addressed to mikea@altjira.com.

2. Introduction

Libpong is an implementation of the pong game where each of two players must hit a ping-pong ball with a racquet. It is derived from and conforms to the Network Model Interface.

Libpong contains two NMI components. Pongnmi is an implementation of the pong task for two players that has an optional X-windows graphical display. Pintnmi is an implementation of an interactive player that uses an X-windows interface.

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

2.1 Companion Software

For simulation frameworks that support NMI components refer to the libnmi documentation. Further information about the interoperability of NMI components can be found in the NMI Simulation Resources documentation.

The pongpkg support package is available to facilitate the application of libpong components within the available simulation frameworks.

2.2 Obtaining

libpong may be downloaded from http://www.altjira.com/distrib/libpong. See also 3.1 Dependencies, and 2.1 Companion Software, for other software that may need to be downloaded and installed.

The latest version of this documentation may be found at http://www.altjira.com/support/libpong/libpong.html.

2.3 Other Documentation

The pongpkg support package includes documentation and examples on how to apply libpong components within the available simulation frameworks. Other relevant support packages may be listed in the NMI Simulation Resources documentation.

Documentation on the implementation of libpong is included within the source code, in particular the primary source files for each NMI component. Further information on how to write an NMI component is included in the libnmi documentation.

See also 2.1 Companion Software for further information on using libpong.

This documentation is also installed to ${prefix}/doc/libpong, where `${prefix}' is the installation directory specified during the build configuration.

3. Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building

3.1 Dependencies

libpong requires both the Network Model Interface library libnmi and the xutil library libxutil.

3.2 Platforms

libpong has been successfully tested on the following systems:

• i686-linux-gnu (Mandrake 8.2 and Redhat 7.2)

3.3 Required Build Tools

The following software is suggested. Other versions may work but have not been tested.

• gcc 3.2
• texi2html 1.64

Package maintenance requires:

• autoconf 2.54
• automake 1.7

3.4 Building

Refer to the README and INSTALL files in the distribution.

4. Overview

4.1 Movements
4.2 Rewards and Scoring
4.3 Coordinate Systems
4.4 Channel Definitions

Libpong abstracts the game as four components, the game component, two optional player components and an optional control component. The game component is defined using the Pongnmi class which has an optional X-windows graphical display.

Games can be played with up to 2 players. If either player is not defined then the racquet for that player does not move. Games can be played with a single player against a wall, by setting the racquet size for the other player to be the width of the court. Libpong also includes an interactive X-windows based player as defined in the Pintnmi class.

The control component can be used to define the initial position and velocity of the ball at the start of each point. Without a control component, the initial position and velocity is set to the previously configured values. The implementation of the control component is not defined within libpong. For an implementation of the control component refer to the accompanying pongpkg support package.

The figure below shows the channels, their tags and their sizes, used to communicate between the components. Two tags are shown for channels that have an NMI component at each end, each tag identifies the channel for one of the components. In this example both players are defined as interactive players using the Pintnmi class, however either or both players could have been replaced with other systems.

4.1 Movements

The length of the court, the distance between the baselines for the players, is defined as the longitudinal distance of the court. The width of the court is defined as the lateral distance of the court.

Each player has a racquet. Each player can move relative to the court in the longitudinal and lateral directions. The racquet for each player can move relative to the player, but in the lateral direction only.

If not configured as restricted, each player and each racquet are not constrained to be within the bounds of the court. The ball is constrained to always be within the bounds of the court, as it bounces of either the walls at the sides of the court or the racquets at the ends of the court.

4.2 Rewards and Scoring

A point ends when the ball passes a racquet at an end of the court. At the end of each point, the Pongnmi component sets a transient reward for each player and increments the score. It also sends out a transient signal indicating that the score has changed which can be used by the control module to set the initial ball position and velocity for the next point (the position is given relative to the centre of the court).

If the Pongnmi module is in automatic play mode, then the ball is automatically started with the configured default initial ball velocity. If the Pongnmi module is not in automatic play mode, then the ball is placed stationary at the centre of the court, waiting for the control module to set it in motion.

If the Pongnmi module is in continuous play mode, then the play is continued whenever a point is lost. In this case the positions and velocities of the ball, the players and the racquets are not reset but are maintained and play continues as if the ball had been properly returned. Note that the scores and the reinforcement signals are still updated and that the player's racquet is not moved to a correct position.

4.3 Coordinate Systems

A number of coordinate systems are used as illustrated in the figure below. Internally Pongnmi uses its own coordinate system as marked in black, with the origin at the bottom left hand corner of the court. Each player communicates with the Pongnmi component using its own coordinate system, as marked in blue and red, with the origin at the bottom left hand corner of the court as seen from the player's perspective. This means that an implementation of a player does not need to know in advance whether it will be player 1 or player 2. In addition each player may communicate with the Pongnmi component using a coordinate system relative to the player.

4.4 Channel Definitions

Note that in each of the following cases the source code is the authorative documentation.

Definition of each index within the motor channels:

1. racquet lateral position relative to the player
2. racquet lateral position relative to the left of the court
3. racquet velocity
4. racquet acceleration
5. player longitudinal position relative to the back of the court
6. player lateral position relative to the centre of the court

Definition of each index within the sensory channels:

1. ball longitudinal position relative to the player
2. ball longitudinal position relative to the back of the court
3. ball lateral position relative to the player
4. ball lateral position relative to the left of the court
5. racquet lateral position relative to the player
6. racquet lateral position relative to the left of the court
7. opposition's racquet lateral position relative to the player
8. opposition's racquet lateral position relative to the left of the court
9. player longitudinal position relative to the back of the court
10. player lateral position relative to the centre of the court
11. player reward

Definition of each index within the control channel:

1. score for player1
2. score for player2
3. ball absolute longitudinal position
4. ball absolute lateral position
5. ball absolute longitudinal velocity
6. ball absolute lateral velocity

Definition of each index within the game channel:

1. score for player1
2. score for player2
3. reward for player1
4. reward for player2
5. score change signal

5. The Pongnmi Class

5.1 Pongnmi Configuration
5.2 Pongnmi Commands
5.3 Pongnmi Input Channels
5.4 Pongnmi Output Channels

5.1 Pongnmi Configuration

The following can be configured using the configure() routine. Note that the classDesc() routine in the source code is the authorative documentation.

time-step=<data> size of the internal time step (0.01) disp-period=<uint> how often to display the graphics (10 timesteps) automatic=<bool> automatic game mode (0) trace=<bool> display a trace of the ball (false) court-long=<uint> longitudinal size of court (78) court-lat=<uint> lateral size of court (23) ball-dlong=<data> initial longitudinal velocity of ball (10) ball-dlat=<data> initial lateral velocity of ball (5) rac1-length=<data> length of racquet 1 (6) rac2-length=<data> length of racquet 2 (6) r1-restrict=<bool> restrict racquet 1 to court (false) r2-restrict=<bool> restrict racquet 2 to court (false) p1-restrict=<bool> restrict player 1 to court (false) p2-restrict=<bool> restrict player 2 to court (false)

5.2 Pongnmi Commands

The following commands can be run using the call() routine. Note that the classDesc() routine in the source code is the authorative documentation.

start-graphics [width=<uint>] [height=<uint>] start the graphics width=<uint> width of window height=<uint> height of window stop-graphics stop the graphics display-graphics display the graphics

5.3 Pongnmi Input Channels

The Pongnmi class defines the following input channels. See 4.4 Channel Definitions for details regarding each channel.

• p1motor

  motor control generated by player 1 (size 6)

• p2motor

  motor control generated by player 2 (size 6)

• control

  control of score and (initial) ball velocity and position (size 6)

5.4 Pongnmi Output Channels

The Pongnmi class defines the following output channels. See 4.4 Channel Definitions for details regarding each channel.

• p1sensory

  sensory data generated for the use of player 1 (size 11)

• p2sensory

  sensory data generated for the use of player 2 (size 11)

• game

  score and reward information (size 5)

6. The Pintnmi Class

6.1 Pintnmi Configuration
6.2 Pintnmi Commands
6.3 Pintnmi Input Channels
6.4 Pintnmi Output Channels

6.1 Pintnmi Configuration

The following can be configured using the configure() routine. Note that the classDesc() routine in the source code is the authorative documentation.

increment=<data> button press increment (0.5) player-long=<data> relative to back of court (0) player-lat=<data> relative to centre of court (0) racquet-lat=<data> relative to player (0)

6.2 Pintnmi Commands

The following commands can be run using the call() routine. Note that the classDesc() routine in the source code is the authorative documentation.

start-graphics [width=<uint>] [height=<uint>] start the graphics width=<uint> width of window height=<uint> height of window stop-graphics stop the graphics display-graphics display the graphics

6.3 Pintnmi Input Channels

The Pintnmi class defines the following input channels. See 4.4 Channel Definitions for details regarding each channel.

• motor

  motor control generated by the player (size 6)

6.4 Pintnmi Output Channels

The Pintnmi class defines the following output channels. See 4.4 Channel Definitions for details regarding each channel.

• sensory

  sensory data for the use of the player (size 11)

7. Examples

Refer to the tutorial in the accompanying pongpkg support package.

To verify that libpong is working properly refer to the examples in the `test' sub-directory in the source tree.

Table of Contents

1. Notices
2. Introduction

2.1 Companion Software
2.2 Obtaining
2.3 Other Documentation

3. Installation

3.1 Dependencies
3.2 Platforms
3.3 Required Build Tools
3.4 Building

4. Overview

4.1 Movements
4.2 Rewards and Scoring
4.3 Coordinate Systems
4.4 Channel Definitions

5. The Pongnmi Class

5.1 Pongnmi Configuration
5.2 Pongnmi Commands
5.3 Pongnmi Input Channels
5.4 Pongnmi Output Channels

6. The Pintnmi Class

6.1 Pintnmi Configuration
6.2 Pintnmi Commands
6.3 Pintnmi Input Channels
6.4 Pintnmi Output Channels

7. Examples

Short Table of Contents

1. Notices
2. Introduction
3. Installation
4. Overview
5. The Pongnmi Class
6. The Pintnmi Class
7. Examples

About this document

• 1. Section One
• 1.1 Subsection One-One
• ...
• 1.2 Subsection One-Two
• 1.2.1 Subsubsection One-Two-One
• 1.2.2 Subsubsection One-Two-Two
• 1.2.3 Subsubsection One-Two-Three     <== Current Position
• 1.2.4 Subsubsection One-Two-Four
• 1.3 Subsection One-Three
• ...
• 1.4 Subsection One-Four