Managers

Most of these Classes have cdefed functions that cannot be read by Sphinx. Read the source if you want to find out more about using them.

class kivent_core.managers.entity_manager.EntityManager

The EntityManager will keep track of the entities in your GameWorld. An Entity is technically nothing more than an entry in an array of unsigned int. The entity is made up of system_count + 1 entries. The first entry is the actual identity of the entity, if it is inactive this will be <unsigned int>-1. The rest of the entries will correspond to the components of your GameSystem with do_components set to True. When a component is active its id will be stored here, if it is inactive the entry will be <unsigned int>-1.

This means technically there is a limit to the number of components and entities you can have at 4,294,967,294. It is however extremely unlikely your game will consist of this many entities or components. Probably KivEnt will also be hopelessly overwhelmed.

EntityManager is typically allocated as part of your GameWorld.allocate.

**Attributes: (Cython Access Only):

memory_index (IndexedMemoryZone): Zoned memory for storing the Entity indices.

system_count (unsigned int): The number of slots reserved per Entitywill be one more than the initialization system_count arg as the first entry is used internally to determine whether an entity is active.

allocate(self, master_buffer, gameworld)

get_entity_entry(self, entity_id)

Will return a list of system_count items corresponding to all the indices that make up the entity. If a value is 4,294,967,295, which is <unsigned int>-1, that component is inactive. If the first value is <unsigned int>-1 the entity itself is currently inactive.

Args:

entity_id (unsigned int): Identity of the entity to return.

Return:

list of ints : The component_id of each of the GameSystem with do_components.

class kivent_core.managers.game_manager.GameManager

System Management

class kivent_core.managers.system_manager.ZoneConfig

Stores the configuration information for a zone in the GameWorld’s GameSystems.

Attributes: (Cython Access Only)

count (unsigned int): Number of entities in this zone.

zone_name (str): Name of the zone.

systems (list): List of the names of the GameSystem that will reserve space for this zone.

class kivent_core.managers.system_manager.SystemConfig

Organizes the ZoneConfigs for a GameWorld. Responsible for adding new zones to the GameWorld and adding systems to those zones.

Attributes: (Cython Access Only)

zone_configs (dict): Hashmap of ZoneConfig objects stored by keys of the zone_name (str).

add_system_to_zone(self, system_name, zone_name)

Adds a system to the zone specified. An already added system cannot be added again (will raise a SystemAlreadyAddedError). Args:

system_name (str): The name of the system to add to the zone.

zone_name (str): The name of the zone.

add_zone(self, zone_name, count)

Creates a new ZoneConfig object and adds it to the zone_configs dictionary. A ZoneAlreadyAddedError will be raised if the zone_name has been previously used. Args:

zone_name (str): The name of the zone to add.

count (int): The number of entities the zone will contain.

get_config_dict(self, system_name)

Returns the config_dict for a specific system_name. This will be a dictionary of zone_name, zone_count pairings. If the default zone, ‘general’, is not registered with the Zone it will be inserted automatically with a DEFAULT_COUNT.

Args:

system_name (str): Name of the system to get the config dict for.

Return:

config_dict (dict): zone_name, zone_count hashmap that includes all the zones that should be allocated for the given system.

class kivent_core.managers.system_manager.SystemManager

Manages the GameSystems attached to the GameWorld as well as the zone configuration for systems which use the IndexedMemoryZone for holding entity data. Supports dictionary style key access of systems directly. There are two types of GameSystem in KivEnt, systems with components, and systems without. The GameWorld will reserve system_count spaces for components for each Entity, meaning that we cannot have more than system_count number of GameSystems that expect to attach components. This value will typically be set with set_system_count as part of GameWorld initialization. If set_system_count is not called, system_count will be system_manager.DEFAULT_SYSTEM_COUNT. Component systems will take up the first N spaces in the systems list, with non-component systems appearing afterwards. There is no limit to the number of non-component GameSystem.

Attributes: (Cython Acces Only)

systems (list): List of the currently active systems, unused slots will have a value of None.

system_index (dict): Maps the name of the systems to their index in the systems list, which corresponds to the component index in the gameworld.entities IndexedMemoryZone.

system_config (SystemConfig): Manages the zone counts for each GameSystem that makes use of the IndexedMemoryZone.

system_count (unsigned int): The number of component systems with space reserved in the gameworld.entities IndexedMemoryZone.

current_count (unsigned int): The number of component systems currently in use.

free_indices (list): List used internally to track component system slots that have had their system removed and are available for reuse.

first_non_component_index (unsigned int): Start of the non-component systems in the systems list.

free_non_component_indices (list): List used internally to track slots for systems that have been removed that do not use components.

update_order (list): Accessible from Python. Provides a list of indices that dictate the order the GameWorld should update the systems in. When setting provide the system_name and internally the appropriate index will be found. From cython you can work directly with the _update_order attribute.

add_system(self, system_name, system)

Adds a new system to the manager. If the system have do_components is True, current_count will need to be less than system_count or a TooManySystemsError will be raised. There is no limit to number of GameSystem that do not do_components. By default the system will be added to the end of the update_order. If you wish to change the order in which systems are updated set the update_order manually after adding all systems.

Args:

system_name (str): The name of the system being added.

system (GameSystem): Reference to the actual system being added.

add_zone(self, zone_name, count)

Adds a new zone to the system_config. Args:

zone_name (str): Name of the zone to be added.

count (unsigned int): Number of entities to add.

allocate(self, master_buffer, gameworld)

Args:

master_buffer (Buffer): The buffer from which the space for the entity IndexedMemoryZone will be allocated.

gameworld (GameWorld): The GameWorld for your application.

configure_system_allocation(self, system_name)

Configures a GameSystem with the system_config using the GameSystem.zones list property. The GameSystem will be registered to use all zones who have their name listed in zones. This should be called during GameWorld.allocate after SystemManager.add_system has been called. Args:

system_name (str): name of the system to be configured

get_system_config_dict(self, system_name)

Gets the config dict for a specific system_name from system_config, which is a zone_name, zone_count pairing for each zone that system will allocate. Args:

system_name (str): Name of the system to get the config_dict for

Return:

config_dict (dict): zone_name, zone_count pairing for the system.

remove_system(self, system_name)

Removes an existing system from the system_manager. Args:

system_name (str): Name of the system to removed

set_system_count(self, unsigned int system_count)

Set the system_count, which is the number of systems that will have space allocated for containing components in the gameworld.entities IndexedMemoryZone. Should be set as part of GameWorld.allocate. Args:

system_count (unsigned int): Number of systems to reserve space for components.

Resource Managers

Resource handling is not quite done yet so consider these sections slightly experimental and know they will probably change in the future. As of 2.1 a new ModelManager has been introduced with slightly different functionality.

class kivent_core.managers.resource_managers.ModelManager(allocation_size=102400)

The ModelManager is responsible for managing all VertexModel that will be used during your game’s rendering. A model is a collection of vertex and index data describing the triangles that make up your entities geometry.]

The ModelManager ensures that all models using the same vertex format are stored contiguously, helping to ensure that your rendering does not have to jump around so much in memory.

If you do not provide custom instructions to the allocation function, the ModelManager will register 100 KiB for each format found in the rendering.vertex_formats.format_registrar. The memory will be split 72/25 vertices to indices.

Remember every entity that uses a model of the same name will share all of that vertex data and modifying ones model will modify all. There is copying functionality built into the loading functions in case you want to create unique models per entity.

Attributes:

models (dict): A dict of all the loaded models, keyed by name.

key_counts (dict): The count of the number of copies made of a certain model. Used internally if we are constructing a copy of an already loaded model.

model_register (dict): Used to keep track of the entities actively using this model. Keyed by model_name will be dicts of key = entity_id, value = system_id of renderer for that entity. If you want to modify a model attached to many entities, use the model_register to find out which entities are actively using that model.

Attributes: (Cython Access Only)

allocation_size (unsigned int): Set during initalization of the ModelManager, this is the amount of space to be reserved for each vertex format if an empty formats_to_allocate dict is provided to allocate. The space will be split 75/25 for vertices/indices.

memory_blocks (dict): A dict of dicts. Each format that gets allocated will have an entry here, that is a dict containing keys: ‘vertices_block’ and ‘indices_block’. Models for that format will be allocated inside these MemoryBlock.

allocate(self, master_buffer, gameworld)

Allocates space for loading models. Typically called as part of Gameworld.allocate.

Args:

master_buffer (Buffer): The buffer to do allocation from. gameworld (GameWorld):

Return:

unsigned int: Number of bytes actually used by the ModelManager

combine_model_infos(self, list infos)

Takes a list of SVGModelInfo objects and combines them into the minimum number of models that will fit that data. Each model will be no more than 65535 vertices, as this is the limit to number of vertices in a single model in ES2.0.

Args:

infos (list): List of SVGModelInfo to combine.

Return:

list: New list of SVGModelInfo combined into the minimum number necessary to display the data.

copy_model(self, str model_to_copy, str model_name=None)

Copies an existing model, creating a new model with the same data. If you set the model_name kwarg the new model will be stored under this name, otherwise the name of model being copied will be used, with do_copy set to True for load_model.

Args:

model_to_copy (str): The name of the model to copy.

Kwargs:

model_name (str): The name to store the new model under. If None the model_to_copy name will be used.

Return:

str: Actual name of the copied model.

get_center_and_bbox_from_infos(self, list infos)

Gets the bounding box and center info for the provided list of SVGModelInfo.

Args:

infos (list): List of SVGModelInfo to find the bounding box and center for.

Return:

dict: with keys ‘center’ and ‘bbox’. center is a 2-tuple of center_x, center_y coordinates. bbox is a 4-tuple of leftmost x, bottom y, rightmost x, top y.

get_model_info_for_svg(self, str source, str svg_name=None, custom_fields=None)

Returns the SVGModelInfo objects representing the elements in an svg file. You can then parse this data depending on your needs before loading the final assets. Use load_model_from_model_info to load your assets.

load_model(self, str format_name, unsigned int vertex_count, unsigned int index_count, str name, do_copy=False, indices=None, vertices=None)

Loads a new VertexModel, and allocates space in the MemoryBlock for its vertex format to hold the model. The model will be stored in the models dict.

Load model does not fill your model with any data you should do that after creating it. Either by accessing the vertices yourself or through a function such as copy_model or load_textured_rectangle.

The kwarg do_copy controls the behavior of the loaded. By default if we find a model has already been loaded under name, we simply return that already loaded model’s name. If do_copy is set to True we will actually create a new model that appends an underscore and number to the name provide. For instance, ‘test_model’ becomes ‘test_model_0’, and then ‘test_model_1’ and so on. Copying ‘test_model_0’ will create ‘test_model_0_0’.

Args:

format_name (str): The name of the vertex format this model should be created with.

vertex_count (unsigned int): The number of vertices in the model.

index_count (unsigned int): The number of indices for the model.

name (str): The name to store the model under.

Kwargs:

do_copy (bool): Defaults False, determines whether to copy the model if we find one with its name is already loaded.

indices (list): If a list of indices is provided, the data will be loaded into your model. Make sure the len(indices) == index_count.

vertices (dict): Vertex data can be supplied in the form of a dictionary containing key is the index of vertex, and the value at the key is a dict with key vertex attribute, value at that attribute.

For instance:

vertices = {
    1: {'pos': (-5., -5.), uvs: (0., 0.)},
    2: {'pos': (-5., 5.), uvs: (0., 1.)},
    3: {'pos': (5., 5.), uvs: (1., 1.)},
    4: {'pos': (5., -5.), uvs: (1., 0.)},
}

Return:

str: Returns the actual name the model has been stored under.

load_model_from_model_info(self, SVGModelInfo info, str svg_name)

Turns the data in a SVGModelInfo to an actual Model for use in your game.

Args:

info (SVGModelInfo): The data for the model you want to load.

svg_name (str): The name of the svg file, previously returned by get_model_info_for_svg.

Return:

str: The key this model is registered under. Will be svg_name + ‘_’ + element_id for the SVGModelInfo.

load_model_from_pickle(self, str file_to_load, str model_name=None)

Loads a previously pickled model.

Args:

file_to_load (str): Name of the file to load.

load_textured_rectangle(self, str format_name, float width, float height, str texture_key, str name, do_copy=False)

Loads a new model and sets it to be a textured quad (sprite). vertex_count will be set to 4, index_count to 6 with indices set to [0, 1, 2, 2, 3, 0].

The uvs from texture_key will be used.

Args:

format_name (str): Name of the vertex format to use.

width (float): Width of the quad.

height (float): Height of the quad.

texture_key (str): Name of the texture to use.

name (str): Name to load the model under.

Kwargs:

do_copy (bool): Defaults False. Kwarg forwarded to load_model, controls whether we will copy the model if name is laready in use.

Return:

str: Actual name of the loaded model.

pickle_model(self, str model_name, str directory_name)

Saves a model to disk using Pickle. Data will be stored as a dictionary containing keys ‘vertices’, ‘indices’, and ‘format_name’.

The name of the file will be os.path.join(directory_name, model_name + ‘.kem’).

Args:

model_name (str): The name of the model to save.

directory_name (str): The directory where you want to save the model.

register_entity_with_model(self, unsigned int entity_id, str system_id, str model_name)

Used to register entities that are using a certain model. Typically called internally as part of Renderer.init_component or the logic associated with setting a RenderComponent.model.

Note: At the moment you should not register the same model on the same entity with multiple renderers. This is not handled. Although I’m not quite certain when you would do that.

Args:

entity_id (unsigned int): Id of the entity being registered.

system_id (str): system_id of the Renderer that this entity is attached to with the model.

model_name (str): Name of the model to register the entity_id with.

unload_model(self, str model_name)

Unloads the model. Freeing it for GC. Make sure you have not kept any references to your model yourself.

Args:

model_name (str): Name of the model to unload.

unload_models_for_svg(self, str svg_name)

unregister_entity_with_model(self, unsigned int entity_id, str model_name)

Unregisters a previously registered entity.

Args:

entity_id (unsigned int): The id of the entity being registered.

model_name (str): The name of the model that entity was registered with.

class kivent_core.managers.resource_managers.TextureManager

The TextureManager handles the loading of all image resources into our game engine. Use load_image for image files and load_atlas for .atlas files. Do not load 2 images with the same name even in different atlas files. Prefer to access kivent.renderers.texture_manager than making your own instance.

get_groupkey_from_texkey(self, tex_key)

get_size(self, tex_key)

get_size_by_name(self, name)

get_texkey_from_name(self, name)

get_texkey_in_group(self, tex_key, group_key)

get_texname_from_texkey(self, tex_key)

get_texture(self, tex_key)

get_texture_by_name(self, name)

get_uvs(self, tex_key)

load_atlas(self, source, datatype='json', dirname=None)

load_image(self, source)

load_texture(self, name, texture)

unload_texture(self, name)

class kivent_core.managers.sound_manager.SoundManager

The SoundManager provides additional features on top of Kivy’s Sound and SoundLoader classes, making it easier for you to integrate sounds into your game, and controlling the ability to play the same sound multiple times simultaneously.

Attributes:

music_volume (NumericProperty): The master volume from 0.0 to 1.0 for music tracks.

sound_volume (NumericProperty): The master volume from 0.0 to 1.0 for sounds. Will be multiplied by the specified volume.

cutoff (NumericProperty): If volume is below this level the sound will not be played at all.

current_track (StringProperty): The name of the music track currently playing.

loop_music (BooleanProperty): If True when one music track finishes playing another will be randomly chosen from the loaded music tracks and scheduled for playing between 0 and max_wait_for_music seconds from now.

max_wait_for_music (NumericProperty): The maximum amount of time to wait before automatically playing another music track when loop_music is True.

music_dict (dict): Dictionary containing all tracks loaded by load_music.

load_music()

Loads a music track under the provided name from the provided address. The entry into music_dict will be a dict containing both the track object loaded by SoundLoader and the file_address, found under those keys.

Args:

track_name (string): Name to load music under.

file_address (string): Location of the file.

Return:

string: The name of the track that has been loaded, will be same as provided arg.

load_sound()

Loads a sound, will load track_count copies of the sound so that up to that many sounds can be played at the same time. Actual number of sounds played will be limited by the number of sound channels available. Returns the integer identifier for the sound to be used with the higher performance play_direct, play_direct_loop, and stop_direct functions as well as making it easier to store sounds in high performance C components for your entities.

Args:

sound_name (str): The name to load the sound file under.

file_address (Str): The actual location of the file in memory.

Kwargs:

track_count (int): The number of times to load the sound, equivalent to the maximum number of instances of this sound can be played simultaneously. Defaults to 4.

Return:

int: the integer identifier for the loaded sound.

on_music_volume()

Callback called when music_volume is changed, will change volume for the current_track if it is not None.

Args:

instance (SoundManager): Should be same as self.

value (float): The new value for the volume.

Return:

None

on_track_stop()

Callback called when on_stop event is fired after a music track quites playing. If loop_music is True another music track will be chosen and begin playing in a randomized amount of time from 0.0 to max_wait_for_music seconds later.

Args:

sound (Sound): The track object that just finished playing.

Return:

None

play()

Wrapper over play_direct that uses the string key for a sound instead of integer key.

Args:

sound_name (string): The string key for the sound to be played.

volume (float): The volume of sound, between 0.0 and 1.0.

Return:

Sound: The instance of the sound being played. Will be None if no sound was played.

play_direct()

Plays the sound specified by the integer key given at the volume provided. If volume is below cutoff, the sound will not be played. If a sound is played, the specific instance of the sound will be returned, otherwise None.

Args:

sound_index (int): The integer key for the sound to be played.

volume (float): The volume to play the sound at, will be multiplied by the sound_volume

Return:

Sound: The instance of the sound being played. Will be None if no sound was played.

play_direct_loop()

Plays the sound specified by the integer key given at the volume provided. If volume is below cutoff, the sound will not be played. If a sound is played, the specific instance of the sound will be returned, otherwise None. The sound’s loop property will be set to True

Args:

sound_index (int): The integer key for the sound to be played.

volume (float): The volume to play the sound at, will be multiplied by the sound_volume

Return:

Sound: The instance of the sound being played. Will be None if no sound was played.

play_loop()

Wrapper over play_direct_loop that uses the string key for a sound instead of integer key. The sound will be set to looping.

Args:

sound_name (string): The string key for the sound to be played.

volume (float): The volume of sound, between 0.0 and 1.0.

Return:

Sound: The instance of the sound being played. Will be None if no sound was played.

play_track()

Plays the track with the given name. If a previous track is playing, current_track is not None, then that track will be stopped.

Args:

track_name (string): The name of the track to play

Return:

None

schedule_play()

Callback for playing a sound by string key for use with Clock.schedule.

Args:

sound_name (string): The string name of the sound.

volume (float): The volume of sound, between 0.0 and 1.0.

dt (float): The time passed since this function was clock scheduled.

Return:

None

stop()

Wrapper over stop_direct that uses a string key for a sound instead of integer key. Stops all instances of the sound being played. Sets loop to False

Args:

sound_name (string): The string key for the sound to be played.

Return:

None

stop_current_track()

Stops the current music track from playing.

Return:

None

stop_direct()

Stops all instances of the sound being played. Sets loop to False Args:

sound_index (int): The integer key for the sound to be played.

Return:

None

class kivent_core.managers.animation_manager.AnimationManager

AnimationManager is responsible for loading and managing animation sequences for the GameWorld. Each animation sequence is a list of frames which stores texture and model for that frame and the duration for which the frame should be displayed in milliseconds

Animation data takes the form: {

‘texture’: texture name for animation, ‘model’ : model name for animation, ‘duration’ : time

}

Attributes:

animations: Dictionary of loaded animations, keyed by name

allocate()

Allocate memory to store frame lists. Called internally during gameworld init.

load_animation()

Responsible for creating a FrameList from a python list specifying frames and storing it in static memory.

Args:

name (str): The name by which to store this animation

frame_count (int): Number of frames in the sequence

frames (list): The list of frames, each item in the list is a dict containing ‘texture’,’model’ and ‘duration’.

load_json()

Parser for a json file containing animation

save_to_json()

Saves the animation specified by items in names to filename

Parameters:

names (list): List of animation names to be stored in the json file

filename (str): Path to json file