class kivent_core.gameworld.GameWorld

GameWorld is the manager of all Entities and GameSystems in your Game. It will be responsible for initializing and removing entities, as well as managing which GameSystems are added, removed, and paused.


state (StringProperty): State is a string property that corresponds to the current state for your application in the states dict. It will control the current screen of the gamescreenmanager, as well as which systems are currently added or removed from canvas or paused.

number_entities (NumericProperty): This is the current number of entities in the system. Do not modify directly, used to generate entity_ids.

gamescreenmanager (ObjectProperty): Reference to the GameScreenManager your game will use for UI screens.

entities (list): entities is a list of all entity objects, entity_id corresponds to position in this list.

states (dict): states is a dict of lists of system_ids with keys ‘systems_added’,’systems_removed’, ‘systems_paused’, ‘systems_unpaused’

entities_to_remove (list): list of entity_ids that will be cleaned up in the next cleanup update tick

system_manager (SystemManager): Registers all the GameSystem added to the GameWorld and contains information for allocation and use of those GameSystem.

master_buffer (object): Typically a Buffer, the base memory from which all other static allocating memory objects will allocate from.

system_count (NumericProperty): The number of systems that will have memory allocated for them in the entities array.

update_time (NumericProperty): The update interval.

size_of_entity_block (NumericProperty): The size in kibibytes of the Entity MemoryBlocks.

size_of_gameworld (NumericProperty): The size in kibibytes of the entire GameWorld’s static allocation.

zones (DictProperty): The zone name and count pairings for static allocation. Dict is zones[zone_name] = entity_count (int).

model_manager (ModelManager): Handles the loading of VertexModels. You should only load model data using this ModelManager. Do not instantiate your own.

managers (dict): Map of all game manageres registered with this GameWorld. Will contain ‘texture_manager’, ‘model_manager’, ‘sound_manager’, and ‘system_manager’ by default. Other GameSystems may register managers or remove them with the register_mnanager and unregister_manager fucntions.

add_state(self, state_name, screenmanager_screen=None, systems_added=None, systems_removed=None, systems_paused=None, systems_unpaused=None, on_change_callback=None)
state_name (str): Name for this state, should be unique.

screenmanager_screen (str): Name of the screen for GameScreenManager to make current when this state is transitioned into. Default None.

systems_added (list): List of system_id that should be added to the GameWorld canvas when this state is transitioned into. Default None.

systems_removed (list): List of system_id that should be removed from the GameWorld canvas when this state is transitioned into. Default None.

systems_paused (list): List of system_id that will be paused when this state is transitioned into. Default None.

systems_unpaused (list): List of system_id that will be unpaused when this state is transitioned into. Default None.

on_change_callback (object): Callback function that will receive args of state_name, previous_state_name. The callback will run after the state change has occured. Callback will be called with arguments current_state, last_state. Default None.

This function adds a new state for your GameWorld that will help you organize which systems are active in canvas, paused, or unpaused, and help you link that up to a Screen for the GameScreenManager so that you can sync your UI and game logic.

add_system(self, widget)

Used internally by add_widget. Will register a previously unseen GameSystem with the system_manager, and call the GameSystem’s on_add_system function.

widget (GameSystem): the GameSystem to add to the GameWorld’s system_manager.
add_widget(self, widget, index=0, canvas=None)

Overrides the default add_widget from Kivy to ensure that we handle GameSystem related logic and can accept both Widget and CWidget base classes. If a GameSystem is added add_system will be called with that widget as the argument.

widget (Widget or CWidget): The widget to be added.

index (int): The index to add this widget at in the children list.

canvas (str): None, ‘before’, or ‘after’; which canvas to add this widget to. None means base canvas and is default.


Typically called interally as part of init_gameworld, this function allocates the master_buffer for the gameworld, registers the zones, allocates the EntityManager, and calls allocate on all GameSystem with do_allocation == True.

clear_entities(self, zones=[])

Used to clear every entity in the GameWorld.

delete_system(self, system_id)
system_id (str): The system_id of the GameSystem to be deleted from GameWorld.

Used to delete a GameSystem from the GameWorld

ensure_startup(self, list_of_systems)

Run during init_gameworld to determine whether or not it is safe to begin allocation. Safe in this situation means that every system_id that has been listed in list_of_systems has been added to the GameWorld.

list_of_systems (list): List of the system_id (string) names of the GameSystems we expect to have initialized.
bool : True if systems all added, otherwise False.
get_entity(self, str zone)

Used internally if there is not an entity currently available in deactivated_entities to create a new entity. Do not call directly.

init_entity(self, dict components_to_use, list component_order, zone='general')

components_to_use (dict): A dict where keys are the system_id and values correspond to the component creation args for that GameSystem.

component_order (list): Should contain all system_id in components_to_use arg, ordered in the order you want component initialization to happen.

This is the function used to create a new entity. It returns the entity_id of the created entity. components_to_use is a dict of system_id, args to generate_component function. component_order is the order in which the components should be initialized

If an Entity is provided as the value in the components_to_use dict, instead of creating a new component the new Entity will use the provided Entity’s component. Be careful to always remove the parent Entity last. This accounting is not currently done for you, you must keep track of Entities linked in this way on your own.

init_gameworld(self, list_of_systems, callback=None)

This function should be called once by your application during initialization. It will handle ensuring all GameSystem added in kv lang have been initialized and call allocate afterwards. Once allocation has finished, the update for GameWorld will be Clock.schedule_interval for update_time. If kwarg callback is not None your callback will be called with no extra arguments.

list_of_systems (list): list of system_id (string) names for the GameSystems we want to check have been initialized and added to GameWorld.
callback (object): If not None will be invoked after allocate has returned and update scheduled. Defaults to None.
on_state(self, instance, value)

State change is handled here, systems will be added or removed in the order that they are listed. This allows control over the arrangement of rendering layers. Later systems will be rendered on top of earlier.


instance (object): Should point to self.

value(string): The name of the new state.

If the state does not exist state will be reset to initial.

register_manager(self, str manager_name, manager_object)

Registers a new GameManager. If manager_name is already registered a GameManagerAlreadyRegistered exception will be raised.


manager_name (str): The name of the manager to register.

manager_object (GameManager): The GameManager object to register.


Used internally to remove entities as part of the update tick

remove_entity(self, unsigned int entity_id)
entity_id (int): The entity_id of the Entity to be removed from the GameWorld

This function immediately removes an entity from the gameworld. The entity will have components removed in the reverse order from its load_order.

remove_widget(self, widget)

Same as Widget.remove_widget except that if the removed widget is a GameSystem, on_remove_system of that GameSystem will be ran.

widget (Widget or CWidget): the child to remove.
timed_remove_entity(self, unsigned int entity_id, dt)

entity_id (unsigned int): The entity_id of the Entity to be removed from the GameWorld.

dt (float): Time argument passed by Kivy’s Clock.schedule.

This function can be used to schedule the destruction of an entity for a time in the future using partial and kivy’s Clock.schedule_once

gameworld.timed_remove_entity, entity_id))
unregister_manager(self, str manager_name)

Unregisters a previously registered GameManager. If no manager was registered under this name a GameManagerNotRegistered will be raised.

manager_name (str): The name the GameManager was registered under.
update(self, dt)
dt (float): Time argument, usually passed in automatically by Kivy’s Clock.

Call the update function in order to advance time in your gameworld. Any GameSystem that is updateable and not paused will be updated. Typically you will call this function using either Clock.schedule_once or Clock.schedule_interval