ursina engine samples

Download Documentation API Reference Samples Asset Store Donate

Entity Basics

What is an Entity?

An entity is a thing in the world, and is the "god class" in ursina.
It's like a GameObject in Unity or an Actor in Unreal.

It can have a position, rotation, and scale.
It can have a model, texture, and color.
It can have an update function, input function, and scripts.
For an overview of all its attributes and functions, see https://www.ursinaengine.org/api_reference.html#Entity

Model

There are several included models like 'quad', 'plane', 'cube', and 'sphere',
but you can also use your own.
To do that simply give the base name of your model and it will glob/search for
the model and take the first one it finds.

Supported file types are:
    • obj
    • bam (binary format)
    • blend (gets auto converted to an obj)
    • ursinamesh (custom human readable format identical to how you'd make a Mesh in code)

Entity(model='name_of_your_model')

Texture

Setting a texture is similar to setting a model. Just give it a name in this case as well:

e1 = Entity(model='cube', texture='texture_name') # other ways are: e2 = Entity(model='cube', texture=e1.texture) # or set it to another Texture e3 = Entity(model='cube', texture=Texture(PIL.Image.new(mode="RGBA", size=(854,480)))) # set a PIL texture e4 = Entity(model='cube', texture='movie_name.mp4') # set video texture

For 2d graphics there's also the Sprite class, which is simply an Entity with a
'quad' model and scale set to automatically fit the size and aspect ratio of the texture.

s = Sprite('texture_name') print(s.aspect_ratio)

Color

e.color = color.red # set it to a color in the color module e.color = hsv(120, .5, .5) # hsv color e.color = rgb(.8, .1, 0) # rgb color e.color = rgb32(16, 128, 255) # rgb color e.color = '#aabbcc' # hex color e.color = e.color.tint(.1) # tint the color e.color = color.random_color() # set it to a random color e.color = lerp(color.red, color.green, .5) # set it to a color half way between red and green

Position

To set the position relative to the parent, set .position:

e = Entity() e.position = Vec3(0,0,0) e.position = Vec2(0,0) e.position = (0,0,0) e.position = (0,0)

You can also set 'x', 'y', 'z' for setting the position on a specific axis.

e = Entity(position=Vec3(1,1,1)) e.x = 0 print(position) >>> Vec3(0,1,1)

To set the position relative to the scene, that is, ignoring the position of any parents, set .world_position:

parent_entity = Entity(position=Vec3(0,2,0)) e = Entity(parent=parent_entity, position=Vec3(0,2,0)) print(e.position) >>> Vec3(0,2,0) print(e.world_position) >>> Vec3(0,4,0) e.world_position = Vec3(0,0,0) print(e.position) >>> Vec3(0,-2,0)

As with position, there's shortcuts for setting world position on individual axes too:
world_x, world_y and world_z

See https://www.ursinaengine.org/coordinate_system.html for more
information on how the coordinate system works.

Rotation

e.rotation = (0,0,0) e.rotation_y = 90

The look_at() method can also be for pointing an entity at something:

other_entity = Entity(position=(10,1,8)) e.look_at(other_entity) # make z-axis(forward) point at other_entity e.look_at(other_entity, axis='up') # optionally define which axis

Scale

Change the size of the entity by setting the scale attribute:

e = Entity(model='cube', scale=(3,1,1))

Update

An Entity's update method will be called automatically:

e = Entity() def my_update(): e.x += 1 * time.dt # dt is short for delta time, the duration since the last frame. e.update = my_update

Or you can implement it by inheriting the Entity class:

class Player(Entity): def update(self): self.x += 1 * time.dt

The third option is to put a function called update in __main__, the starting script.
You'll see this in a lot of examples since it's convenient for small scripts.
Keep in mind this won't work if you import a module with an update function defined at module level.

def update(): print('update')

Input

The same goes for the input method:

class Player(Entity): def input(self, key): if key == 'w': self.position += self.forward if key == 'd': self.animate('rotation_y', self.rotation_y + 90, duration=.1) if key == 'a': self.animate('rotation_y', self.rotation_y - 90, duration=.1)

Mouse Input

Entities can react to the mouse as long as they have collider.
Buttons will have one by default, but you can also assign one.

To get the entity currently under the mouse:

print(mouse.hovered_entity)

To check if and entity with a collider is hovered by the mouse:

print(my_entity.hovered)

There are also functions for handling mouse clicks and hover/unhover.
These only works if the Entity has a collider and the function/callable is assigned.

on_click() on_double_click() on_mouse_enter() on_mouse_exit()

Example using on_click:

def action(): print('Ow! That hurt!') Entity(model='quad', parent=camera.ui, scale=.1, collider='box', on_click=action) # on_click should be a function/callable/Func/Sequence

on_mouse_enter and on_mouse_exit example:

b = Button(scale=(.5, .25), text='zzz') b.on_mouse_enter = Func(setattr, b, 'text', 'Hi, friend :D') b.on_mouse_exit = Func(setattr, b, 'text', '''No! Don't leave me ;-;''')

Other Magic Functions

Sometimes you want side effects when you enable/disable an entity, like play an animation or something.

on_enable() on_disable() on_destroy()