Difference between revisions of "Programming"

Revision as of 02:27, 26 January 2015

After the initial whitewood has been built, it is time to bring it to life by programming the control system and adding game rules.

Languages

The programming language being used is going to be dictated primarily by the hardware control system chosen. Off the shelf systems such as P-ROC or Fast have a close relationship to PyProcGame, which is dedicated exclusively to the P-ROC, or the Mission Pinball Framework which supports both P-ROC and FAST and is a more higher level programming framework.

For more lower-level control, there is the libpinproc library for P-ROC boards, which allow binding into other languages and building of custom frameworks using things like SDL or SFML which provides access to OpenGL and other graphics APIs.

If using custom hardware, you likely have the means for writing control software without the help of this guide.

Pinball Frameworks

• Mission Pinball: Currently supports both P-ROC and FAST controllers, written in Python
• PyProcGame: Developed specifically for the P-ROC controllers, written in Python
• libPinPROC: Lower level C library for P-ROC
• Python: Language used for the Pinheck board

Rules

As pinball hardware advanced in complexity from simple relays to transistors, so did game rules. Electromechanical (EM) pinball machines often struggled to register multiple switch hits at the same time, while early Solid State (SS) games allowed fast response times and multiple concurrent switch hits to be registered. Faster CPUs with more memory allow for the deeper rule sets of modern pinball.

Rules can be as simple as Complete the rollovers for bonus multiplier to stacking several mode-scoring multiballs together.

Maintaining State

Deeper rule tracking requires maintaining State, which is a map (in memory) of the current switch conditions, such as:

• What was the state of all the switches N seconds ago?
• Has anything changed in N seconds?
• How many times has a switch been hit total?

These are all States and the control program keeping track of these allows for modes and other advanced rules.

Think of an orbit shot: two switches, one of the left side orbit entry, one of the right side orbit entry. An orbit is complete if both switches are hit in order. It takes time for the ball to travel from one side to the other - there may be 5 seconds or more if the ball is slow, struggles to get to the apex, or dribbles down the other side. A failed orbit may count two hits to only one of the switches. It may count only one hit if the ball just makes it and rolls back down. The orbit shot is a good example of needing to know the previous switch state, the question then becomes, how many previous states to track?

Example: If an orbit is a multiball jackpot shot, how to handle when a second ball enters the left orbit before the first ball has triggered the right orbit switch? This means an orbit that can be fed from either direction is probably not a good way to score a jackpot. This is why a ramp shot is very easy to track a jackpot on - ramps have an apex and once your past the apex, any exit switch hit from the ramp is easily countable.

Another example of an advanced rule would be tracking the order of something - having five drop targets that give an extra bonus if hit in order of one to five, or five to one. This is a variable outside of standard switch state and it has to be managed outside of just target hits, as well as be reset on a ball drain, reset if a mode changes, or reset if the drop targets are reset.

Code complexity is increased by remembering the state of that variable and which targets have been hit or not between changing players.

The deeper rules become, the more variables, flags and timers that are needed to be tracked and managed, and the more difficult the code becomes to debug and maintain.

Some other examples of maintaining state:

• If a target enables a kickback, will extra kick backs be added if it is already lit?
• Knowing how many balls are in the ball trough before lighting the add-a-ball insert.

Game Logic Flow

For an example of a typical layout of general game rules and how the logic should flow, see the Rule Flow subpage.

Priority

Modes, display events and sounds all need to be prioritized relative to each other - for example, background displays or sounds are a lower priority than a switch hit or score display.

For example, if a high priority sound is playing, and the ball hits a switch that triggers a low priority sound effect, the control program can skip playing the lower priority sound, or play it at a lower volume. Or, if there is a display event for a pop bumper hit, it will be higher priority than the score display.

Light Shows

With modern CPU-controlled lamps, it is possible to use general illumination, flashers and playfield insert lamps to produce Light Shows during Attract mode to bring attention to the game from a passer-by, or while the game is active to convey information to the player.

For example, lighting lamps from the bottom of the playfield up to the top, then turn them off from the bottom up would be a distinct lamp show used during Attract mode. Below shows part of the attract mode for High Speed which uses multiple techniques.

Mission Pinball Framework supports the concept of Light scripts, which allow a maker to script what lamps are lit, for how long, and at a specific brightness to produce various effects.

Light Groups

Lights can be put into groups of similar lamps that allow for specific light effects. For example High Speed has the circular rev lamps, which lend themselves to a circular lamp effect, or the lamps in a row above them are well suited to a side-to-side effect.

Backbox

Most modern games have abandoned controlled lamps in the backbox to save on costs, but a garage maker has no such restrictions on creativity and can add various light effects to the backglass. Separating sections off to light separately is a common technique.

Settings / Preferences

Audits

Auditing for a pinball machine involves keeping a tally of various activities, such as:

• Total plays
• Total balls played
• Coins dropped
• Replays awarded

Creating audit tracking is easy, programming-wise. When a game is over, you would simply increment the "total games played" variable up by one.

Settings

These are values that modify the game rules. Most modern games have dozens of settings that dramatically alter game play. Some examples include:

• Free Play
• Balls Per Game
• Replay enabled
• Replay score percentage
• Extra balls enabled
• Ball Save enabled

Diagnostics

Another benefit of the switch from EM to Solid State electronics was the ability to include Diagnostics as a standard part of new games. The operator can run quick diagnostics on a machine without having to lift the playfield. Some example include:

• Switch Test: With the playfield glass removed, switches can be individually tested, with the number being shown on numerical scoring games, or the matrix coordinates being shown on DMD pins.
• Sound Test: With modern computer-based pinball machines, this test might be obsolete.
• Coil Test: Coils can be individually fired for checking faults, or all coils fired in order to test all coils.
• Light Test: Insert lights can be checked for burned out bulbs by flashing them individually.
• Unique Mechanism Test: This would apply to parts unique to the machine. An example would be the rotating box on Bally Theatre of Magic.

Scoring

For scoring, a separate scoring subroutine should be used and called as needed. This routine can do checks for earning game-wide rewards (points, replay) each time a player's score is incremented. Having it separate also allows for incorporating a double score mode for adding twice the amount of points without having to incorporate the mode check in each target hit routine.

Pseudocode example:

def add_score(points):
	game.curplayer.score = game.curplayer.score + points
	if curplayer.score => game.settings.replayscore:
		award_replay()

Bonus Lanes

Bonus lanes are typically located at the top of the playfield, consisting of three or more lanes a ball can fall through at random. A ball falling through one of the lanes will light the lane. A bonus will be awarded, typically with a bonus multiplier (but can vary) if all the lanes are lit.

Beginning with Williams Firepower, hitting the flipper buttons would cycle the lit lanes left or right, allowing the player to move the unlit lane under the falling ball, achieving the bonus. Bonus lanes are frequently incorporated into the skill shot.

Layout:

• One switch per lane.
• Each lane will have one light associated with it. Some games have two lights per lane, creating two sets of bonus lanes (Example: Williams Barracora').

Pseudocode example:

// variables
cur_bonus = 1  
lane1 = off 
lane2 = off
lane3 = off
tmplane = off

	def switch1_hit
		lane1 = on
		play_sound(boink)
		curplayer.add_score(10)
		lights.lane1 = on

	def switch2_hit
		lane2 = on
		play_sound(boink)
		curplayer.add_score(10)
		lights.lane2 = on

	def switch3_hit
		lane3 = on
		play_sound(boink)
		curplayer.add_score(10)
		lights.lane3 = on

// and the code for cycling the bonus lanes, tied to flipper button

// code for checking all bonus lanes
	def check_all_lanes()
		with curplayer
			if  (lane1 = on) + (lane2 = on) + (lane3 = on)
				increase_bonus()
				play_sound(yay_bonus!)
				display_msg("BONUS INCREASED")
				// shut off states & reset!
				lights.lane1 = off
				lights.lane2 = off
				lights.lane3 = off

// the code for increasing the bonus multiplier 
// bonus held not implemented

	def increase_bonus()
		curplayer.cur_bonus = curplayer.cur_bonus + 1
		// give any special award if it is at a high #

Game Modes

These are modes that are specific to the game in question and relate to the theme or specific special devices included in the design. They can also fall outside regular gameplay - for example, Bally Safecracker has a special Assault the Vault mode triggered by using a unique token in the coin slot. Or Williams Black Knight and Time Fantasy, which have a special post-game timed mode governed by time earned in regular gameplay, where you have unlimited balls to score extra points.

General Modes

These are modes that are general to most games, rather than rules specific to the machine's theme.

Game Start

Game End

After the game ends, cleanup of the playfield device and some variables internal to the software should be done. Examples in no particular order include:

• Release any locked balls from kickers
• Release any locked balls from vertical upkickers
• Disable flippers
• Return any mechanical devices to Game Start state
• Check for any high scores achieved by any players and record initials
• Run Replay Match
• Set number of current players to zero
• Null/delete any player objects
• Delete the game session object
• Audits - increase # of games played, etc.

Replay Match

Ball Seek

In the event a ball gets stuck and the player is unable to play, many machines will go into a Ball Seek mode. All mechanisms that interact with the ball will individually fire after a specified "idle" delay in an attempt to free the stuck ball. The Ball Seek mode will often run continuously until the missing ball is found, or only repeat a few times at which point the ball is marked as lost and game play continues, with the software compensating for the missing ball as best as possible.

A timer is updated to check for any idle time of the ball - any switch hits (indicating ball movement) resets this timer. If no switch activity occurs for a specified period of time (as set by an operator setting), the Ball Seek subroutine would be run.

Put the timer reset calls through all the switch detection events (except for shooter lane, tilt plumb, buttons) as those switch hits indicate a healthy running ball session.

A ball in the shooter lane should disable the timer, with it starting after confirming a ball has been launched and is in play. For convenience sake, invoke the ball seek timer after a player has passed or failed the skill shot. So, just after shutting down the skill shot (if implemented), start the ball save timer.

Shut down the ball save timer once the ball session is over.

Pseudocode example:

 // invoke the ball seeker routine
	def bs_timer_start()
		// ball saver invoked
		bs_timer_countdown = 60
		
// reset the timer
   	def bs_timer_reset()
		bs_timer_countdown = 60
    
// shut down the timer entirely
	def bs_timer_shutdown()
		bs_timer_countdown = -1

// this runs when the timer has expired
 	def ball_saver()
		if ( bs_timer_countdown = 0 ) 
			// fire the coils
			coils.popbumper1.fire()
			// fire drop target reset
			coils.dtbank1.fire()
			// and so forth
			// reset timer and hopefully we won't have to run it again
			bs_timer_reset()

// example of the 1 of many target hits
// that show the timer reset routine
	def leaftarget1_hit()
		score.addpoints(50)
		sound.play("boop")
		bs_timer_reset()

Ball Save

Ball save is when a ball in play is drained out shortly into the ball session. This routine can be triggered via the outlanes or center drain.

Typically Ball Save is either time-based or score-based. The allowed time for ball save to be active can be set via Preferences.

Extra Ball

Skill Shot

Skill Shots are available when the player first plunges the ball. Plunging the ball at the right strength, or at the right time, or hitting a specific switch, will earn the player a reward - generally a bonus multiplier or a large points bonus.

Used in conjunction with a physical plunger (as opposed to an autoplunger), plunging the ball at just the right strength to hit a specific switch will award the Skill Shot value.

Some shots are Strength-based, where a group of targets or switches can be hit by the ball from the plunger, and the indicated target or switch, when hit, will award the value. Of these types, variations include the Side style where the ball is aimed at targets in a vertical alignment (as in Williams No Good Gofers), or Over where the ball is plunged over the switches, as shown in this example from Williams Pinbot:

For games with autoplungers, there are Time-based examples where the player must time the activation of the plunger to correspond with the ball hitting a lit target - Williams Terminator 2 is an example of this type. Many autoplunger games use a randomly-chosen Bonus Lane, where the skill shot is achieved if the ball goes through the indicated lane at the end of a plunge.

When coding, the logic is:

• Initialize the skill shot mode at the begin of a ball session
• End the skill shot after the player has passed or failed

Tilt

Although not thought of as a mode, it fits the same model - it is triggered from one or multiple switch events, in this case, the switch being the tilt bob. When the tilt is triggered enough times (and after warnings issued), the game will end the current ball.

A Tilt should trigger the following:

• Disable Flippers
• Shut off GI and any insert lights
• Shut off music
• Disable pop bumpers
• Disable slingshots
• Do not award end-of-ball bonus points

Once the ball is returned the trough, regular play resumes.

An additonal mode is the Slam Tilt, triggered by a switch on the coin door. The main difference is that the whole game for all players will be immediately ended, as to punish the player for being rough with the machine.

Status Report

Generally activated by holding down both flippers.

Status Report

Device Modes

These are general modes that trigger specific mechanical devices.

Kickback

See the Kickback subpage for hardware details.

For the kickback, some checks will need to be done to ensure that the ball is out of the outlane area. One solution is to leave it active for a specified period of time to give an additional kickback to ensure the ball is out.

Other triggers may include:

• A sound or call-out indicating to the player that kickback is enabled
• A sound or call-out when kickback is invoked

The action to activate the kickback is to pulse the solenoid. What is critical is getting the timing correct where it does not fire too soon, or too late, where the ball will be missed. Some timing adjustments will need to be done to find the sweet spot where it will handle the most amount of ball velocity variations.

Pseudocode example:

// variables
kickback_enabled = (on/off) 

// scope: ball session

	def enable_kickback()
		ballsess.kickback_enabled = on
		lights.kb = flashy
		play.sound("kickback is on!")

// switch hit event for the left outlane
// determines if you drain or kick

	def leftoutlane_sw()
		if ballsess.kickback_enabled = on
			( kickback_fire() )
		else
			score.addpoints(50)
			sound.play("aww shucks")

// fire the kickback

	def fire_kickback()
		sound.play("misspiggy hiyah!")
		coils.kickback.pulse()

    	// insert any additional "keep hot" code here
		// okay, shut off the kickback
		disable_kickback()

// shut off kb
// also shut this off if you tilt

	def disable_kickback()
		ballsess.kickback_enabled = off
		lights.kb = off

Ball Trough

See the Ball Trough subpage for hardware details.

Pseudocode example:

TBD

Drop Targets

See the Drop Targets subpage for hardware details.

For a drop target bank, a check is needed after every drop target hit. As an example of using state to manage the game, a player could be awarded points for hitting the drop targets in order (Example: Bally Centaur), or award points for completing multiple sets of drop target banks.

Pseudocode:

// variable scope(current ball session)
	dbank1 = off
	dbank2 = off
	dbank3 = off
	
	def dbank1_hit()
		score.addpoints(50)
		dbank1 = on
		play_sound(boink)
		check_dropbank1()

	def dbank2_hit()
		score.addpoints(50)
		dbank2 = on
		play_sound(boink)
		check_dropbank1()

	def dbank2_hit()
		score.addpoints(50)
		dbank3 = on
		play_sound(boink)
		check_dropbank1()
	 
// check to see if all the drop targets have been hit
	
	def check_dropbank1()
		if (dbank1= on) & (dbank2=on) & (dbank3=on)
			// reward for completing drop target bank
			play_sound(chaching)
			score.addpoints(200)
			
			// reset the variables
			dbank1= off
			dbank2 = off
			dbank3 = off
			
			// reset 'em
			coils.dbank1.pulse()

// separate routine for resetting drop target bank ,
// add this to the "ball begin" routine

	def reset_drop_bank()
		coils.dbank1.pulse()

Slingshots

See the Slingshots subpage for hardware details.

Pseudocode:

TBD

Kicker Hole

See the Kicker Hole subpage for hardware details.

Pseudocode:

TBD

Divertors

See the Divertors subpage for hardware details.

Pseudocode:

TBD

Vertical Up-Kickers

See the VUK subpage for hardware details.

Pseudocode:

TBD

Sound

Sound is a critical component of any pinball machine. EM games used bells and chimes to inform the player while modern games use digitized voice callouts and stereo music.

Some things to consider when deciding on how to incorporate sound in a game include:

• Avoid playing sounds continuously over the top of one another. For example, having an explosion sound when a pop bumper is triggered - if the ball is getting a lot of pop bumper action and it triggers three pops in very fast succession, restarting the sound event on each trigger would sound like white noise. Thus, choose not to play the same sound effect unless N time has passed (say 3 seconds), or never play the same sound affect at the same time.
• Too many sound effects playing over each over mutes the effect it should have on the player and can be confusing.
• Timing of sound events should be kept short, as the longer the sound, the more likely it will overlap with another switch event trigger, leading to too many overlapping sound events or the white noise problem mentioned earlier.
• Normalize the volume of all the sound effects to the same level to maintain a common volume level on the machine itself.

sound assignments

Music loops

Basic sounds

voice callouts