See Source
HEAT2D
DOCUMENTATION
See Source
HEAT2D
DOCUMENTATION
Manual
Dark Theme
a
Heat2D is an open-source, simple and concise 2D game engine project. You can contribute and see the source here.
This manual helps you learn how to use Heat2D. If you are a beginner, you should read the pages under Getting started category. If not, you can use here as a reference.
Here are the main features provided by the engine
Heat2D is an open-source project and you are totally free to contribute. Just follow up some basic rules and we all would be fine.
If you don't will to contribute but having an issue, you can open a new Issue here.
Or if your issue keeps staying unfixed, you can get help by contacting us from social platforms.
Here are the platforms you can reach me and the community:
Installing Heat2D with PIP is as easy as this
pip install heat2d
If you can't install Heat2D with PIP, you can download the source from here and build it manually
python setup.py installAfter installation, you can import Heat2D and check if it's version up-to-date.
Here is a simple snippet showing the base syntax of Heat2D
import heat2d
engine = heat2d.Engine()
@engine.add
class Main(heat2d.Stage):
def created(self):
print("Main stage is initialized!")
def update(self):
if engine.key_pressed("space"):
random_color = heat2d.Palette("rainbow").get_random()
engine.window.clear_color = random_color
engine.run()You can continue reading tutorials from tutorial index.
Keyboard, mouse and controller inputs can be managed using Engine's related methods.
There are three main methods to interact with keyboard input: heat2d.Engine.key_pressed(key), heat2d.Engine.key_released(key) and heat2d.Engine.key_held(key). The key parameter is just a string indicating the keyboard key, there is a list below (click spoiler to see the list) and a keyboard example demo. If none paramaters given, any key press will return True.
Key combinations
You can also check key combinations. E.g key_pressed("ctrl + z"), key_held("alt + b + 0")...
White-spaces and upper/lower cases doesn't matter while entering the key parameter, so "space" and "SpaCE" are the same just as like "shift+ctrl+z+b" and "SHIFT + ctrl + Z+b" ...
You can control numpad keys both ways: key_pressed("0", numpad=True) or key_pressed("n0")
While controlling special characters, you can use left and right keyword arguments or place prefixes.
key_held("ctrl") checks both left and right ctrl keys, you can limit this by doing Engine.key_held("ctrl", right=True) or key_held("rctrl")
Key Q
Keycode 113
Special? false
Parameter "q"
There are three main methods to interact with mouse input: heat2d.Engine.mouse_pressed(button), heat2d.Engine.mouse_released(button) and heat2d.Engine.mouse_held(button). The button parameter is just a string indicating the mouse button, there is a list below (click spoiler to see the list) and a mouse example demo. If none paramaters given, any button press will return True.
You can check mouse wheel state with heat2d.Engine.mouse_wheel_up() and heat2d.Engine.mouse_wheel_down()
Key
Parameter
TODO
This alpha version is not released yet
|
Core class of the whole library. Manages stages, events, handles inputs and such. Can be also accessed from dispatcher object: heat2d.DISPATCHER.engine |
|
Basic usage:
from heat2d import *
engine = Engine() #Create the Engine instance
#Add a new component (Stage in this case) to the engine
@engine.add
class Main(Stage):
def created(self):
print("Main stage is created!")
engine.run() #Start the engineYou can find more information on Project Flow or Tutorial index.
class heat2d.Engine()windowMain window object
Type: Window
rendererMain renderer object
Type: Renderer
mouseMouse position
Type: Vector2
func run()Starts the engine
func stop()Stops the engine
func add(component)Adds component to the engine
Parameters
current_stageCurrent stage's name
Type: str
func get_current_stage()Returns current stage
Return: Stage
func get_stage(name)Returns desired stage
Parameters
Return: Stage
func change_stage(stage)Changes the current stage
Parameters
Raises
deltatimeElapsed time between two frames
Type: int
fpsCurrent FPS of your game
Type: int
max_fpsFPS limit
Type: int
Warning: There are input handling functions below. See Input handling page to learn about usable parameters and further information.
func key_pressed(key)Returns True at the moment the key gets pressed
Parameters
Raises
Return: bool
func key_released(key)Returns True at the moment the key gets released
Parameters
Raises
Return: bool
func key_held(key)Returns True if key is pressed
Parameters
Raises
Return: bool
func mouse_pressed(button)Returns True at the moment the mouse button gets pressed
Parameters
Raises
Return: bool
func mouse_released(button)Returns True at the moment the mouse button gets released
Parameters
Raises
Return: bool
func mouse_held(button)Returns True if mouse button is pressed
Parameters
Raises
Return: bool
func mouse_wheel_up()Returns True if mouse wheel gets turned upwards
Return: bool
func mouse_wheel_down()Returns True if mouse wheel gets turned downwards
Return: bool
Window where your game gets displayed on.
You can use properties to customize window quickly:
from heat2d import *
engine = Engine() #Engine instance
engine.window.size = (1920, 1080) #Make window display 1920x1080 pixels
engine.window.title = "My awesome game!" #Change window title
engine.window.clear_color = Color("Deep Sky Blue") #Change window display's background color to a nice blue color.
#See Color page for more information about using colors
class heat2d.Window() sizeSize of the window display
Type: tuple(width, height)
widthWidth of the window display
Type: int
heightHeight of the window display
Type: int
titleTitle of the window
Type: str
iconFilepath to the window icon
Type: str
clear_colorWindow's display clear color
Type: Color
centerCenter point coordinates of window
Type: Vector2
func take_screenshot(filepath, area=None)Takes a screenshot and saves it
Parameters
func toggle_fullscreen()Toggles fullscreen mode
fullscreenThe window is in fullscreen mode or not
Type: bool
func is_active()Is the window active or not
Return: bool
Stage system is one of the most important concepts in Heat2D. You can think them like individual parts of your game that does their individual jobs. Such as main menus, game levels etc..
Basic stage:
from heat2d import *
engine = Engine() #Engine instance
#Add MyStage to the engine
@engine.add
class MyStage(Stage):
#This method is called when stage is created
def created(self):
print("MyStage is created!")
#This method is called every tick by engine
def update(self):
if engine.key_pressed("space"):
engine.window.take_screenshot("screenshots/001.png")
print("Screenshot saved to screenshots folder.")
class heat2d.Stage()func add(gameobject)Adds gameobject to the stage
Parameters
func get(name)Returns the GameObject matched with name
Parameters
Return: GameObject
func created()This method is meant to be overrode
func update()This method is meant to be overrode
The following errors are thrown by the engine
exception heat2d.errors.NoStageDeclaredThis is raised when user has not added any stage to engine
exception heat2d.errors.UnknownKeyThis is raised when the given key is not valid in heat2d.Engine.key_pressed(key), heat2d.Engine.key_held(key) and heat2d.Engine.key_released(key)
exception heat2d.errors.UnknownMouseButtonThis is raised when the given mouse button is not valid in heat2d.Engine.mouse_pressed(button), heat2d.Engine.mouse_held(button) and heat2d.Engine.mouse_released(button)
exception heat2d.errors.NetworkingErrorThis is raised when a networking-wise issue happened
Sprites are basically images bound to GameObjects. Sprites can also be animated, see animation introduction page for further information about animations.
class heat2d.Sprite(source, loader=None)Parameters
sizeSize of the sprite
Type: int
widthWidth of the sprite
Type: int
heightHeight of the sprite
Type: int
Warning: size, width and height properties of sprite is valid if sprite has only one source. (When you create it as Sprite("sourceimage.png")) If you created your sprite using a SpriteSheet you would want to get width, height or size from SpriteSheet's sources because every frame of the sprite sheet animation can be in different sizes depending on how you created your animation source. You can get current size of the sprite while the sprite sheet animation playing by Sprite.get_current_frame() which returns a Source object.
angleAngle of the spritey
Type: int (degrees)
func rotate(angle)Rotates the sprite by given angle
Parameters
func rotate_to(vector)Rotates sprite towards the given position
Parameters
func scale(factor)Scales the sprites by given factor
Parameters
paletteSprite's palette which is going to be used during rendering
Type: Palette
func add_animation(animation)Adds new animation group to the sprite
Parameters
func play_animation(name, duration=None, loop=False)Plays an animation group
Parameters
func stop_animation(wait=False)Stops the current playing animation
Parameters
has_animationDoes sprite have any animation groups or only one static image
Type: bool
sheetsThis is a dictionary including all animation groups of the sprite by their names. You can access a specific group by their name Sprite.sheets["group name"] or the current group Sprite.sheets[Sprite.current_animation]
Type: dict
current_animationName of the current playing animation group's name
Type: str
current_frameCurrent frame number of the current playing animation
Type: int
playingIf any animation is playing currently
Type: bool
func get_current_frame()This function returns a Source object which includes image information about current frame of the current playing animation
Return: Source
Color object is used anywhere has a relation with color.
Some examples:
from heat2d import Color
Color(0, 255, 0) #Lime (alpha is 255 by default)
Color("#ff0000") #Red
Color([0, 0, 255, 128]) #Half-transparent blue
Color("Lime")
c = Color("deepskyblue")
print(c.to_tuple()) #output -> (0, 191, 255, 255)
Note: While creating a color object if you are using a color name as argument, typing and whitespaces doesn't matter. These are all the same; "Medium Violet Red", "medium violet red", "mediumvioletred", "mediumViolet red"
Table of built-in colors in Heat2D:
Light Salmon
Salmon
Dark Salmon
Light Coral
Indian Red
Crimson
Firebrick
Red
Dark Red
Light Red
Coral
Tomato
Orange Red
Gold
Orange
Dark Orange
Light Orange
Lemon Chiffon
Rod Yellow
Papayawhip
Moccasin
Peach Puff
Pale Golden
Khaki
Dark Khaki
Yellow
Dark Yellow
Light Yellow
Lawn Green
Lime
Dark Lime
Light Lime
Green Yellow
Yellow Green
Spring Green
Pale Green
Sea Green
Dark Sea Green
Medium Sea Green
Light Sea Green
Olive
Dark Olive
Light Olive
Olive Drab
Green
Dark Green
Light Green
Aquamarine
Dark Aquamarine
Pale Turqoise
Turqoise
Dark Turqoise
Cadet Blue
Teal
Cyan / Aqua
Light Cyan / Aqua
Dark Cyan / Aqua
Powder Blue
Sky Blue
Light Sky Blue
Deep Sky Blue
Steel Blue
Light Steel Blue
Dodger Blue
Comflower Blue
Royal Blue
Medium Blue
Navy
Midnight Blue
Blue
Dark Blue
Light Blue
Lavender
Thistle
Plum
Violet
Orchid
Magenta / Fuchsia
Blue Violet
Dark Violet
Dark Orchid
Dark Magenta
Indigo
Purple Blue
Dark Purple Blue
Light Purple Blue
Purple
Dark Purple
Light Purple
Hotpink
Deep Pink
Pale Violet Red
Medium Violet Red
Pink
Dark Pink
Light Pink
Comsilk
Blanched Almond
Bisque
Navajowhite
Wheat
Burly Wood
Tan
Rosy Brown
Sandy Brown
Golden Rod
Peru
Chocolate
Saddle Brown
Sienna
Brown Red
Maroon
Brown
Dark Brown
Light Brown
Snow
Honeydew
Mint Cream
Azure
Alice Blue
Ghost White
White Smoke
Sea Shell
Beige
Oldlace
Floral White
Ivory
Antique White
Linen
Misty Rose
White
Gainsboro
Silver
Dim Gray
Slate Gray
Light Slate Gray
Dark Slate Gray
Deep Gray
Black
Light Black
Gray
Light Gray
Dark Gray
class heat2d.Color(color[, ...])Parameters
Color(r, g, b[, a])Color([r, g, b[,a]])Color("#hexcode")Color("Color name") rRed channel of the color
Type: int
gGreen channel of the color
Type: int
bBlue channel of the color
Type: int
aAlpha channel of the color
Type: int
hHue property of the color
Type: float
sSaturation property of the color
Type: float
lLightness property of the color
Type: float
func negative()Returns negative version of the color
Return: Color
func grayscale()Returns grayscale version of the color
Return: Color
func to_tuple()Returns RGBA channels as tuple
Return: tuple
func distance(color)Returns the distance between self and other color in RGB space
Parameters
Return: float
func distance2(color)Returns the distance squared between self and other color in RGB space
Parameters
Return: float
Palettes are simply groups of colors. Colors in the palette are sorted by their lightness level by default. You can get a specific color by indexing the palette object, use Palette.get_closest(color) to get the most similar color or use Palette.get_random() method to get a random color.
|
Palettes also can be applied to sprites. Sprite's original colors will not get affected, they will just be rendered using that pallette. |
|
class heat2d.Palette(source)Parameters
func get_random()Returns a random color
Return: Color
func get_closest(color)Returns the most similar color to given color
Parameters
Return: Color
func get_average()Returns the average color of all colors in the palette
Return: Color
Postprocess effects are built-in shaders that are rendered after all other game rendering stuff is done.
You can use load_postprocess() method of Renderer to load postprocess effects into your game. The postprocess effect gets loaded to Renderer.postprocess attribute, which is a Shader object so you can customize postprocess effects in the runtime using uniforms
There is the list of current built-in postprocess effects:
Warning: If showcase examples below bug out, just refresh the page
Mosaic pixelating effect
Uniforms
• pixelSize - How big the pixels will be (float)
Single-pass gaussian blur effect. There are four blur effects named blur7, blur11, blur13 and blur15. Higher the kernel size, better quality but lower performance
Uniforms
• resolution - Resolution of blur (float)
3D stereo illusion effect
Uniforms
• offset - Distance of the effect from origin (float)
Vignette effect
Uniforms
• strength - Strength of the effect (float)
• spread - How much the effect spreads (float)
Motion trail effect. (This effect doesn't work really good and the image below doesn't reflect how really this effect work)
Uniforms
• alpha - Trail gets longer when alpha gets higher (float)
Color correction effect
Uniforms
• brightness - Image brightness (float)
• contrast - Image contrast (float)
RGB channels effect
Uniforms
• red - Red channel of image (float)
• green - Green channel of image (float)
• blue - Blue channel of image (float)
HSV channels effect
Uniforms
• hue - Hue channel of image (float)
• saturation - Saturation channel of image (float)
• value - Value channel of image (float)
class heat2d.math.Vector2(x[, y])Parameters
Vector2(x, y)Vector2((x, y))Vector2(length)Operator overloadingsfunc __add__()Vector2 + Vector2
Vector2 + int/floatfunc __sub__()Vector2 - Vector2
Vector2 - int/floatfunc __mul__()Vector2 * Vector2
Vector2 * int/floatfunc __truediv__()Vector2 / Vector2
Vector2 / int/floatfunc __floordiv__()Vector2 // Vector2
Vector2 // int/floatxX component of the vector
Type: int/float
yY component of the vector
Type: int/float
func length()Returns magnitude of the vector
Return: float
func distance_to(vector)Returns the distance to the given vector
Parameters
Return: float
func angle_to(vector)Returns the angle to the given vector
Parameters
Return: float (degrees)
func get_angle()Returns angle of the vector
Return: float (degrees)
func set_angle(angle)Sets angle of the vector
Parameters
func rotate(vector)Rotates the vector around it's origin
Parameters
func rotate_around(vector, angle)Rotates the vector around another vector
Parameters
func dot(vector)Returns dot-product with given vector
Parameters
Return: float
func perp()Returns a vector perpendicular to current one
Return: Vector2
func inverse()Returns the inverted version of the vector
Return: Vector2
func normalize()Returns a vector in same direction but length of 1
Return: Vector2
func to_tuple()Returns (x, y)
Return: tuple