game2dboard

This Python GUI package provides a graphical user interface (GUI) for 2D arrays (matrix) to make it easy to create board-style games.

What is the aim of this library?
I created this project to help my students from an introductory course on computer programming at the University of Passo Fundo (Brazil) to write programs with two-dimensional arrays in an easy and fun way. I think it can be useful for others.
What types of games can be created?
Any game that can be represented as a two-dimensional array, such as checkers, life, tic-tac-toe, chess, 2048, minefield, among many others.

Installation

You can use the pip to install game2dboard:

pip3 install game2dboard

Or install the latest release by cloning the repository:

git clone https://github.com/mjbrusso/game2dboard.git 
cd game2dboard
python3 setup.py install --user

Usage

The API is documented bellow and within the docstrings.

This simple code only provides an overview. See the examples for more details.

Before running, copy this and this files into a img/ folder (credits).

from game2dboard import Board


def mouse_fn(btn, row, col):    # mouse calback function
    b[row][col] = 1 if not b[row][col] else 0

b = Board(3, 4)         # 3 rows, 4 columns, filled w/ None
b[0][0] = 1
b.title = "Click me!"
b.cell_size = 120       
b.cell_color = "bisque"
b.on_mouse_click = mouse_fn
b.show()

Result

Galery

Some screenshots from examples.


Memory Game 58 SLOC View source	Snake 86 SLOC View source
Kill the mosquito 75 SLOC w/ Background image and Sounds View source

API

Creation

game2dboard.Board(nrows, ncols)
Creates a Board.
- nrows : int – The number of rows.
- ncols : int – The number of columns.

Indexer

self[i][j]
Gets/sets the value at row i, column j.

When assigning a value, the GUI will be updated. If there is an .png file in the img/ folder whose name is the same as the new value, it will be drawn at position [i][j] of the board. Otherwise, the value will be displayed as text.

Example:
```
  b[1][0] = 100            # draw 'img/100.png' @ row 1, column 0
  b[0][2] = "correct"      # draw 'img/correct.png'
  b[3][0] = "wait.png"     # draw 'img/wait.png'
```

Properties

Use properties to access board attributes like public fields.
Example:

  b.title = "Hello"       # Sets the window title
  sz = b.size             # Gets the total number of elements

Board properties

size : int (readonly)
Number of elements in the array
nrows : int (readonly)
Number of rows in the array.
ncols : int (readonly)
Number of columns in the array.
width : int (readonly)
Board width, in px. Only available after .show()
height : int (readonly)
Board height, in px. Only available after .show()
title : str
Gets or sets the window title.
cursor : str
Gets or sets the mouse cursor shape. Setting to None hides the cursor.
See avaliable cursor names in https://anzeljg.github.io/rin2/book2/2405/docs/tkinter/cursors.html
background_image : str
Gets or sets the background image file name. The .png file must be in the folder img/
Setting this property forces grid_color, margin_color and cell_color to None.
margin : int
Gets or sets the board margin (px).
cell_spacing : int
Gets or sets the space between cells (px).
margin_color : str
Gets or sets the margin color.
cell_color : str
Gets or sets cells color
See available color names in https://htmlcolorcodes.com/color-names/
grid_color : str
Gets or sets grid color.
cell_size : int | (int, int)
Gets or sets the cells dimension (width, height).

Event properties

on_start : function()
Gets or sets the game started callback function.
The GUI is ready and the program is going to enter the main loop.
on_key_press : function(key: str)
Gets or sets the keyboard callback function.
See key names in https://anzeljg.github.io/rin2/book2/2405/docs/tkinter/key-names.html
on_mouse_click : function(button: int, row: int, column: int)
Gets or sets the mouse callback function.
on_timer : function()
Gets or sets the timer callback function.

Methods

show()
Create the GUI, display and enter the run loop.
clear()
Clear the board, setting all values to None.
close()
Close the board, exiting the program.
shuffle()
Random shuffle all values in the board.
fill(value, row=None, col=None)
Fill the board (or a row, or a column) with a value.
- value – The value to store
- row (int) – Index of row to fill. Default=None (all rows)
- col (int) – Index of column to fill. Default=None (all columns)
copy()
Returns a shallow copy of the array (only data, not the GUI) into a regular Python list (of lists).
load()
Copy data from regular Python 2D array (list of lists) into the Board.
create_output(**kwargs)
Create a output message bar.
- kwargs:
  - color = str
  - background_color = str
  - font_size = int
print(*objects, sep=' ', end='')
Print message to output bar.
Use like built-in print() function.
start_timer(msecs)
Start a periodic timer that executes the a function every msecs milliseconds
The callback function must be registered using .on_timer property.
- msecs (int) – Time in milliseconds.
stop_timer()
Stops the current timer.
pause(msecs, change_cursor=True)
Delay the program execution for a given number of milliseconds.
Warning: long pause freezes the GUI!
- msecs (int) – Time in milliseconds.
- change_cursor (bool) – Change the cursor to "watch" during pause?

What about Sound?

To play sounds in the game, use my audioplayer package.

audioplayer is a cross platform Python 3 package for playing sounds (mp3, wav, ...). It provides the key features of an player, such as opening a media file, playing (loop/block), pausing, resuming, stopping, and setting the playback volume.

from audioplayer import AudioPlayer
import os

# Background music 
bgm_file = os.path.join(os.path.dirname(__file__), 'background.mp3')
bgm = AudioPlayer(bgm_file)
bgm.volume = 50         # 50% volume
bgm.play(loop=True)     # start playing

# Audio player is lazy loaded: resources loading is delayed until the first call to play() method.
explosion = AudioPlayer(os.path.join(os.path.dirname(__file__), 'explosion.mp3'))

def timer_callback():
    if collides(enemy, bullet):
        explosion.play()

For a full example using AudioPlayer, see Kill the Mosquito.

What's in the roadmap?

on_mouse_over = function(button: int, row: int, column: int) : event occurs when the mouse pointer is moved onto an cell (maybe with a button pressed)
save_file(filename) : Dump array data to a file
read_file(filename) : Restore array data from file
redim(new_ncols, new_nrows) : Useful to grow or shrink the board, for example, on level up.

How to Contribute

Submitting an issue

Use the issue tracker to submit bug reports and features or enhancements requests.

Translating

You can contribute by translating this document into other languages (except en and pt_br).

Submitting a pull request

If you can improve anything in this project, feel free to add a pull request.

License

game2dboard is under MIT license. It can be reused within proprietary software provided that all copies of the licensed software include a copy of the MIT License terms and the copyright notice.

Anupam02/game2dboard