py-fizz🔗ℹ

Fun with fizzics!

Py-fizz is a language for creating physics simulations and games. Compiles to Python and runs in the context of Pygame and Pymunk. But Racket is the compile-time language, and provides a purely functional API for doing awesome physics stuff.

Py-fizz is divided into two languages. The first is a higher-level one, used for creating levels and simulations out of pre-built gadgets: e.g. Bowling balls, balloons, motors, etc. Eg.:

(simulate

(wooden-level

(bowling-ball)))

There is also a lower-level language for defining your own such gadgets. For example, the bowling-ball gadget might be defined as:

(define (bowling-ball)

(mass 100000

(make-dynamic (h:bitmap "./imgs/bowling-ball.png"))))

These docs describe both the high and low level languages.

1 Basic vocabulary🔗ℹ

Before we start, there are a few basic concepts.

First of all, everything in py-fizz is some kind of physical object. There are three basic kinds: cosmetic, dynamic, and static.

Cosmetic objects do not collide with anything. They are just for show.

Dynamic objects do collide. Also, they can move around.

Static objects also collide, but they do not move around.

There is one other kind of object, which is a "composite" object. This just means that the object is composed of more basic objects.

For example, the car object is composed of three wheels and a crate. The wheels and crate are all dynamic objects. The car is a composite object.

(simulate

(wooden-level

(car)))

One last critical concept! Objects can be parameterized. For example, the car is a function that takes a speed and/or ANOTHER OBJECT.

(simulate

(wooden-level

(car 1 (bowling-ball))))

Or...

(simulate

(wooden-level

(car 1 (balloon))))

Or...

(simulate

(wooden-level

(car 1 (enemy))))

And so on. You can pass in any basic object to the car function, and you’ll get a new composite object back. You could then pass this new car into any other function that takes a composite object.

For example, maybe you want to be able to shoot a balloon-car out of a cannon...

(simulate

(wooden-level

(cannon (car 1 (balloon)))))

The image above probably doesn’t communicate exactly how cool this is. Let’s check out a gif...

So that’s the basic idea. You create objects. You make those into composite objects. And you can combine composite objects to get even cooler composite objects.

And so on.

Exercise: Can you figure out how to make a car with a cannon on top that shoots out other cars?

2 py-fizz High Level🔗ℹ

The High Level library consists of various gadgets (composite and basic) that all tend to have a consistent look and feel, as well as physical properties that work well together. Many of the gadgets are parameterized, so you can make your own new gadgets with them (like that balloon car shooter seen above).

This part of the documentation lists the provided gadgets and shows you how to compose them to make new ones.

2.1 Basic Gadgets🔗ℹ

This is just a pretty-looking space for running simulations. There are static walls on all sides, and a cosmetic (wooden) background in the middle. It will dynamically resize if what’s inside doesn’t fit in the default 600x600 space.

Simple bowling ball. High mass.

No parameters on this one. But you can alter its properties with functions like toggle-static, mass, initial-velocity, etc.

Dynamic crate. Falls by default. If you want to use it as a platform, call toggle-static on it to convert it to a static object.

Low mass, circular object.

Floats. (Obeys opposite gravity.)

If it is attached to other objects, it will pull them upward.

Like a regular balloon, but it can be destroyed by clicking on it.

It can also be destroyed if it collides strongly with other objects.

A dynamic object that causes you to lose the game if any of them are destroyed. Useful when building puzzles.

A dynamic object that causes you to win the game if all of them are destroyed. Useful when building puzzles.

A dynamic object that rotates continually. Good for vehicles.

Use negative numbers to make it rotate the other direction.

A dynamic object that rotates continually. It’s pinned to one spot. Good for conveyor belts.

Use negative numbers to make it rotate the other direction.

Makes a see-saw contraption, on one side is a bowling ball with a strong downward starting velocity. On the other side is whatever object you supply.

Note that although this function accepts static, dynamic, cosmetic, or composite objects, it is most exciting when you pass in a dynamic object (or a composite object that contains dynamic objects).

Makes a car. You can control speed and direction with the speed parameter (negative numbers go counter clockwise).

The second parameter controls what object is on top of the car. Passing in a dynamic object is the simplest thing.

If you pass in a static object, the car will be stuck in the air, "pinned" by the static object. Usually not what you want. (Use toggle-static to switch your static object to a dynamic one before passing it into the car function.)

ADVANCED USAGE: If you pass in a composite object, you pust also pass in a join-object as the third parameter. This determines which part of the composite object to connect the wheels to.

Let’s take a moment to see how cool it is to be able to make flying cars...

Makes a dynamic rectangle that looks like a pipe. Good for platforms, walls, falling pipes, etc.

Attaches the given number of balloons to the given object. The length of the balloon string can also be configured.

Creates the given number of motors in a horizontal row. The speed determines three things: the speed (obviously), the direction (negative is counter-clockwise), and the color (blue for counter-clockwise, red for clockwise).

Takes the object and returns a composite object that looks like the original, but is really a bunch of dynamic objects constructed from a sliced up image of the original.

This is how breakable-balloons explode when destroyed.

Note that fragments are computationally expensive. Keep the resolution and the destroy-after parameters low.

Returns a static cannon that shoots the provided object when clicked.

The angle and the power of the shot can be adjusted.

Returns a static treasure chest that turns into the provided object when clicked. Good for puzzles.

An icon of the provided object is displayed above the chest, so the user knows what to anticipate.

3 py-fizz Low Level🔗ℹ

3.1 Top Level🔗ℹ

3.2 Basic Constructors🔗ℹ

procedure (make-static object [#:collider collider]) → static?

object : (or/c h:image? cosmetic? layout? physical?)

collider : collider? = circle-collider

procedure (make-dynamic object [#:collider collider]) → dynamic?

object : (or/c h:image? cosmetic? layout? physical?)

collider : collider? = circle-collider

procedure (make-cosmetic object) → cosmetic?

object : (or/c h:image? cosmetic? layout?)

procedure (make-pivot object) → pivot?

object : (or/c h:image? cosmetic?)

3.3 Setting Physical Properties of Objects🔗ℹ

procedure (motorize speed object) → dynamic?

speed : number?

object : dynamic?

procedure (gravity direction object) → dynamic?

direction : (list/c number? number?)

object : dynamic?

procedure (elasticity amount object) → dynamic?

amount : number?

object : dynamic?

procedure (angle amount object) → dynamic?

amount : number?

object : (or/c dynamic? static?)

procedure (friction object [energy angle]) → static?

object : (or/c dynamic? static?)

energy : number? = 10000

angle : number? = 0

procedure (ttl time object) → dynamic?

time : number?

object : (or/c dynamic? static? cosmetic?)

procedure (mass amount object) → dynamic?

amount : number?

object : dynamic?

procedure (initial-velocity direction object) → dynamic?

direction : (list/c number? number?)

object : dynamic?

procedure (toggle-static object) → (or/c dynamic? static?)

object : (or/c dynamic? static?)

procedure (width object) → number?

object : (or/c dynamic? static? cosmetic? composite?)

procedure (height object) → number?

object : (or/c dynamic? static? cosmetic? composite?)

3.4 Making composite objects🔗ℹ

The easiest way to make a composite object is to use a spatial layout function: above, beside, or overlay.

These place two objects in a spatial relation to each other.

Additionally, objects can be associated with physical properties: e.g. they might have a joint connecting them. If this is the case, you’ll create the composite object with a two-step process – 1) establish the physical relation ship (e.g. with the spring-joint function), and then place the two objects into a spatial relationship (e.g. with the above function).

(let* ([b1 (bowling-ball)]

[b2 (bowling-ball)]

[b1-with-connection

(pin b1 b2)])

(simulate

(above b1-with-connection b2)))

Note that the pin function takes b1 and returns a new version of b1 that has a pin joint relationship to b2. But you still need to place both b1-with-connection and b2 into a relation with each other.

(You’ll get a runtime error if you don’t.)

3.4.1 Spatial Relations for Composite Objects🔗ℹ

Spatial relations may be established between any two objects. They do not need to be related to each other physically.

procedure (above object ...) → composite?

object : (or/c dynamic? static? cosmetic? composite?)

procedure (beside object ...) → composite?

object : (or/c dynamic? static? cosmetic? composite?)

procedure (overlay object ...) → composite?

object : (or/c dynamic? static? cosmetic? composite?)

3.4.2 Physical Relations for Composite Objects🔗ℹ

As stated above, spatial relations may be established between any two objects. They do not need to be related to each other physically.

The opposite, however, is not true. If you create a physical relationship between two objects, you must ALSO relate them spatially.

Think of it this way: If you say that two objects are physically related (e.g. they have a connecting joint), you also need to say where those objects are in the universe. The only way to place things into the universe is to relate them spatially to each other.

Keep that in mind with all of the functions in this subsection.

Returns a new version of the first object.

Returns a new version of the pivot.

Returns a new version of the first object.

Returns a new version of the first object.

3.5 Runtime Behaviours🔗ℹ

Collisions can be filtered out based on friction and kinetic energy loss.

3.6 Misc🔗ℹ