Getting started

These bindings are easy to apprehend and learn if you come from the C++ library; class, methods and functions names are the same. We’ll see here step by step everything you need to know to get started with pySFML!

Of course, you need first to have pySFML downloaded and installed on your computer. To do that, read the download section, it provides all explanations you’ll need to install on your favourite platform. At worst, you’ll need to compile.

After reading this you can jump to the single Tutorials that summarizes all the large, potentially surprising, changes that you should be aware of. You’ll be able to start coding serious project with the documentation at hand.

Diving In

Note

On Windows, typing these commands directly in a console might cause the console to freeze, in which case it is better to save the lines of code (without the ‘>>>’ prompt) to a file to run later.

Open a terminal and run the Python interpreter. Now we can experiment:

>>> from sfml import sf
>>> w = sf.RenderWindow(sf.VideoMode(640, 480), "My first pySFML Window - or not ?")
>>> w.clear(sf.Color.BLUE)
>>> w.display()
>>> w.size = (800, 600)
>>> w.clear(sf.Color.GREEN)
>>> w.display()
>>> w.title = "Yes, it's my first PySFML Window"
>>> w.display()
>>> w.capture().show()
>>> w.close()
>>> exit()

Short Example

As a start, let’s compare the python short example with the C++ one. Here it is:

from sfml import sf


# create the main window
window = sf.RenderWindow(sf.VideoMode(640, 480), "pySFML Window")

try:
   # load a sprite to display
   texture = sf.Texture.from_file("cute_image.png")
   sprite = sf.Sprite(texture)

   # create some graphical text to display
   font = sf.Font.from_file("arial.ttf")
   text = sf.Text("Hello SFML", font, 50)

   # load music to play
   music = sf.Music.from_file("nice_music.ogg")

except IOError: exit(1)

# play the music
music.play()

# start the game loop
while window.is_open:
   # process events
   for event in window.events:
      # close window: exit
      if type(event) is sf.CloseEvent:
         window.close()

   window.clear() # clear screen
   window.draw(sprite) # draw the sprite
   window.draw(text) # draw the string
   window.display() # update the window

First, you can notice the interface is not far different from the original and remains quite the same; the interface has been pythonized.

Importing

The module hierarchy in pySFML models the C++ API rather closely. As such, you may import them directly:

import sfml.system

As with any other python package, you may find yourself using aliases to more conveniently access the API:

import sfml.system as sf

sf.sleep(sf.seconds(5)

The problem with this approach is that it breaks down rather quickly when you want to start to use mutiple submodules from the sfml package. For this reason, we provide a convenience module named sf, which imports all of the other submodules:

from sfml import sf

sf.sleep(sf.seconds(5)

For the sake of keeping examples brief, the rest of the documentation uses this convenience module. However, should you ever become curious as to where a particular object resides, their fully qualified names linked.

Window Creation

There’s no difference here. if you want to give a style:

window = sf.RenderWindow(sf.VideoMode(640, 480), "pySFML Window", sf.Style.TITLEBAR | sf.Style.RESIZE)

Loading Resources

Instead of checking every time if the resource has effectively been loaded, pySFML takes advantages of the Python mechanisms. Just enclose your resource loading processes in a try-except bloc and Python will tell you when something goes wrong.

As you can see in the code, it will trigger an exception IOError in accordance with the Python’s exception rules.

To follow the same convention as the standard Python library and so, offer a better integration, openFromFile and loadFromFile have been renamed into from_file.

Event Handling

To iterate over the pending events, use the generator that Window.events return. It’s similar to the polling event process.

for event in window.events:
    print(event)

Note

sfml.window.Window.poll_event() and sfml.window.Window.wait_event() do exist.

Once you get an event you need to process it. To do that, you need to check its type as you would do in C++. pysfml2 doesn’t provides the attribute type that tells you what event it is (keyboard event, mouse event, mouse move event, etc). Therefore you need to use the built-in function type() to determine its type.

if type(event) is sf.CloseEvent:
   window.close()

You can get a list of the event class in the documentation, section window, as event handling is located in the window module ;).

Updating the Screen

Don’t forget to clear, draw and update the screen.

window.clear() # clear screen
window.draw(sprite) # draw the sprite
window.draw(text) # draw the string
window.display() # update the window

Vectors

As Python is not a typed language, you don’t have to care about the type when you use sf::Vector<T>. Python just needs to know if it’s a two or three dimensional vector, after, you can store any numeric type inside.

vector2 = sf.Vector2()
vector2.x = 5
vector2.y = 1.16

vector3 = sf.Vector3()
vector3.x = Decimal(0.333333333)

x, y, z = vector3 # you can unpack the vector