who is this for

This is the advanced tutorial. If you know python and wish to get started with using pyaudiogame right away, this is the place for you. If the words class, method, attribute, variable, function, argument, import, module, calling or self are at all alian to you, save yourself the confusion and head over to the other tutorial

basic layout

In pyaudiogame, everything is based off the pyaudiogame.App class. You can either call an instance and add your settings and logic to it, or create a child of App and sub-class the functions you need. It is built for both. Head down to the hello world basic and hello world advanced to see the two different ways.

important things to know

Here there will be a basic description for the important parts of pyaudiogame, but for a more advanced description, see the api or read the code under pyaudiogame/.

App class

methods

The app class has 4 methods and several attributes that are important: For the methods we have:

def logic(self, actions):
	"""Overwrite this and put your game logic here. This is just a place-holder for now"""
	pass

It is where every script in your game goes and is one of the two methods you should sub-class. actions is a dict of all the events you can moniter. The most important events from actions are: actions['key'] is a string of the current key, like "up", "down", "space", "f", "f1", "escape", "\"...

actions['mods'] This is a list of the modifier keys like: "shift", "ctrl", "alt", "shift"...

There is also actions['mousex'], actions['mousey'] and actions['mouseClicked'] which deal with the mouse. For more info, see the API.

def run(self):
	"""Call this when you are ready to start your game. It will run your main loop and create your screen"""
	#game looping code

Call this at the bottom of your main app module and it will start the application. It is not advised to override this unless you know pyaudiogame very well.

def key_repeat(self, on=True, delay=1000, delay_before_first_repeat=1):
	"""Call this function to either start what happens when a key is held down or to turn it off."""
	#Code that deals with held down keys

If you wish to have a new key event triggered every interval (like for walking), turn this on by calling it like:

MyApp.key_repeat(delay=500)

delay is the amount of time between each re-sending of the event in milliseconds, so the above will trigger every half-second. When you wish to turn it off, do

MyApp.key_repeat(on=False)

def set_defaults(self):
	"""Call this function to change the default variables"""
	pass

This is only for subclassing. If you don't wish to over-ride the init method, but would like to change the default variables easily, this method is run at initialization.

self.event_queue.schedule(self, function, delay=0, repeats=1, before_delay=False, *args, **kwargs)

Hey wait, that's not a method!

No, that's why it is at the end of the methods and before the attributes. This is the event queue. You call MyApp.event_queue.schedule and pass in a function, the amount of time you wish to pass, how many times you would like the function to trigger, if you would like the delay before or after the function and any arguments or key-word arguments you wish to pass to your function. A call would look like:

MyApp.event_queue.schedule(hello_world, 1)

This would run hello_world() 1 second later.

default attributes

The first two can be passed in to the __init__ call:

self.title = title
self.fps = fps

title is the name of the screen and fps is the amount of times the game loop runs each second. The default is 30 and that should be plenty for an audio game. Most graphical games run at 60, but that is because graphics take a lot of effort to get smoothe. Here are the other defaults, but you can learn more about them at the API.

#Default variables that can be changed, but are not called
#For the screen:
#The two below numbers are in pixels, the current screen is a little box on the screen
self.windowwidth = 640
self.windowheight = 480
#Full screen expands everything and fills the whole screen
self.fullscreen = False
#If the mouse should be visible or not
self.mouse = False
#Our event queue
self.event_queue = ticker.Scheduler(time_format=0.001)
#A hard-coded exit key, 1 is escape, 2 is alt + f4 and 0 is nothing **WARNING** if there is no exit key you need to go to command prompt window and hit ctrl + c to exit the window!
self.exit_key = 1

Hello world basic

*see the source for this in examples/hello_world.py*

code:

import pyaudiogame
spk = pyaudiogame.speech.speak

#First create a basic app
app = pyaudiogame.App("My hello world app")

#Now make some game logic
def logic(actions):
	"""Our game logic function that gets run every iteration of our app's running loop"""
	if actions['key'] == "space":
		spk("Hello world")

#Put our logic into the app
app.logic = logic

#Run our app
app.run()

hello_world basic explanation

If you didn't figure it out, you need to press space to get hello world to speak...
This is a pretty self-explanatory piece of code, we call an instance of App, replace the logic method and run it.
Some things to take note of:

	import pyaudiogame
	spk = pyaudiogame.speech.speak

hello_world_advanced

The source can be found at examples/advanced/hello_world_advanced.py

code:

#This is a hello world example using the more powerful sub-classing option
from pyaudiogame import App
from pyaudiogame.speech import speak as spk

class MyApp(App):
	"""We create our class as a child of App and we can sub-class the logic function which is run each iteration of the game loop"""
	def logic(self, actions):
		"""actions is a dict of all the input events, like keyboard and mouse"""
		if actions['key'] == "space":
			spk("Hello world")

if __name__ == '__main__':
	#call the run function for our app to begin the game loop. press escape to exit.
	MyApp().run()

hello_world_advanced explanation

#This is a hello world example using the more powerful sub-classing option
from pyaudiogame import App
from pyaudiogame.speech import speak as spk

class MyApp(App):
	"""We create our class as a child of App and we can sub-class the logic function which is run each
		iteration of the game loop."""

Here is where we are saying that this is the App class, but I'm going to rename it and if I wish, I can add and change methods, even the ones that App already has. This is what we do, we change the
logic()
method:

	def logic(self, actions):
		"""actions is a dict of all the input events, like keyboard and mouse"""
		if actions['key'] == "space":
			spk("Hello world")

The advantage of writing our code this way is so we have access to self. We can also use the namespace of the function through self.

if __name__ == '__main__':
		#call the run function for our app to begin the game loop. press escape to exit.
		MyApp().run()

	def set_defaults(self):
		self.exit_key = 2

Other important modules

There is a built-in cashing module, so you can store what ever you wish in there.

ui

The ui folder:
pyaudiogame.ui
has a list of frequently used scripts. There is a menu script and a typing script currently. To learn more about them, see the API under ui.