Basics

How to use it

- ⚠️ NOTE :  before reading this remind yourself that: 
- Some explanations might be unclear or wrong if so then please report them so it can changed.

Creating the canvas

Start by instancing a canvas like so:

canvas = oz.Canvas("#") 
# The  argument is given what the canvas will be filled with.

and then instancing a camera so that we can render the scene.

camera = oz.Camera(canvas , 
{"x" : 10 ,"y" : 10} , {"x" : 0 ,"y" : 0} , "camera")
#First argument is the canvas that it belongs to.
#Second argument is the size of the camera.
#Thid argument is the position of the camera.
#And the last one is the name.

Now try rendering it:

print(camera.render())

You should see a square filled with "#"

Adding Sprites

It's cool and all but a little boring to have just an empty canvas. Let's add a sprite:

sprite = oz.Sprite(canvas , "S" , {"x" : 3 , "y" :3} , "first_sprite" ) 
# "canvas" is the canvas that is associated with the sprite in question
# "S" is character that the sprite will be represented with.
# and "first_sprite" is the name of the sprite

feel free to add multiples sprites :) !

Moving functions

If you wanted to move them then simply do that:

# add 1 to x-axis:
sprite.change_x(1) 

# add -1 y-axis:
sprite.change_y(-1)

#set x-axis
sprite.set_x(1)

#set y-axis
sprite.set_y(3)

#set position (x and y)
sprite.set_position({"x" : 3 , "y" : 5})

#add to x and y axis
sprite.change_postion(1 , -1)
#first argument is for "x" and the second for "y"

Useful sprite methods

There are a few important function for sprites that needs to be known. For example if you want to delete an object

albert_the_sprite.kill()

or to rename it

albert_the_sprite.rename("albert")

but also to handle collisions

albert_the_sprite.get_colliding_objects()

"get_colliding_objects" is a method that returns all sprites names that colliding with the sprite that execute the method (albert_the_sprite here)

we can check collision like so:

canvas = oz.Canvas("#")

albert_the_sprite = oz.Sprite(canvas , "a" , {"x" : 0 , "y" : 0} , "albert")
robert_the_sprite = oz.Sprite(canvas , "r" , {"x" : 0 , "y" : 0} , "robert")
billy_the_sprite = oz.Sprite(canvas, "b" , {"x" : 2 , "y" : 0} , "billy")

if "robert" in albert_the_sprite.get_colliding_objects():
  
  print("collides with:" , albert_the_sprite.get_colliding_objects())
  print("robert collided with albert.")

else:

  print("robert didn't collide with albert.")

Now if we wanted to execute a method to robert with could use the "get_sprite()"

canvas.get_sprite("robert").set_position({"x" : 0 , "y" : 0})

Please note that you will need to execute this method throught the canvas that is associated with the sprite.

Groups

"groups" is an optional argument of the object "Sprite" that can be used to call a method to each sprite that belong to this group or check collisions between groups. Please note that each sprite can have multiple groups since the argument is a list.

Collision with groups

First things first you need to actually define the group that the sprite belongs to:

snake_the_sprite = oz.Sprite(canvas , "s" , {"x" : 0 , "y" : 0} , "snake" , ["animal"])
cat_the_sprite = oz.Sprite(canvas , "c" , {"x" : 0 , "y" : 0} , "cat" , ["animal"])

apple_the_sprite = oz.Sprite(canvas , "a" , [0 , 0] , "apple" , ["fruit"])

now we can simply check collision:

print(apple_the_sprite.get_colliding_groups())
#output : {"fruit" , "animal"}


if "animal" in apple_the_sprite.get_colliding_groups():
    print("The fruit was eaten by an animal ")

else:
    print("The fruit is still here :D !")

the method "get_colliding_groups()" returns a list that contains every groups that collides with the sprite that executes the method.

Calling groups

Let's imagine that we are making a game where if a button is pressed all the doors should open well it would simple just to use the method "call_group()".

but first we need to create our own sprite type : "Door" we will do so by creating a New class called you guessed it : "Door"

#inherits from class "Sprite"
class Door(oz.Sprite):
  #Custom Sprite Type
  #That has Custom Methods
  def open_door(self):
    print(f'door : "{self.name}" was opened !' )

and then we can instance the door and call the method

canvas = oz.Canvas("#")

door_one = Door(canvas , "1" , {"x" : -4 , "y" : 2} , "door_one" , "door")
door_two = Door(canvas , "2" , {"x" : 2 , "y" : -3} , "door_two" , "door")
door_three = Door(canvas , "3" , {"x" : 3 , "y" : 7} , "door_three" , "door")

canvas.call_group("door" , "open_door" )

#output : 
#door : "door_one" was opened !
#door : "door_two" was opened !
#door : door_three was opened !

but now let's say we want to give and argument well it's super easy :)

#add method to the door class
def multiply_x_axis(self , times):
    self.set_x(self.position["x"] * times) 

then just call the method:

canvas = oz.Canvas("#")

door_one = Door(canvas , "1" , {"x" : -4 , "y" : 2} , "door_one" , "door")
door_two = Door(canvas , "2" , {"x" : 2 , "y" : -3} , "door_two" , "door")
door_three = Door(canvas , "3" , {"x" : 3 , "y" : 7} , "door_three" , "door")

print(canvas.sprite_position_dict.values()) #prints all positions
#output before call : dict_values([ {"x" : -4 , "y" : 2}, {"x" : 2 , "y" : -3}, {"x" : 3 , "y" : 7}])

canvas.call_group("door" , "multiply_x_axis", 2 )
print(canvas.sprite_position_dict.values()) #prints all positions multiplied by 2
#output after call : dict_values([{"x" : -8 , "y" : 2}, {"x" : 4 , "y" : -3}, {"x" : 6 , "y" : 7}])

giving multiple arguments is possible.