diff --git a/docs/index.rst b/docs/index.rst index 8213526..f2ce896 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -15,11 +15,33 @@ from the `dataclasses` module can be useful to help write compact Component classes. -The World Class ---------------- - .. autoclass:: esper.World - :members: - +The World context +----------------- + +.. autofunction:: esper.switch_world +.. autofunction:: esper.delete_world +.. autofunction:: esper.list_worlds +.. autofunction:: esper.create_entity +.. autofunction:: esper.delete_entity +.. autofunction:: esper.entity_exists +.. autofunction:: esper.add_processor +.. autofunction:: esper.remove_processor +.. autofunction:: esper.get_processor +.. autofunction:: esper.component_for_entity +.. autofunction:: esper.components_for_entity +.. autofunction:: esper.add_component +.. autofunction:: esper.remove_component +.. autofunction:: esper.get_component +.. autofunction:: esper.get_components +.. autofunction:: esper.has_component +.. autofunction:: esper.has_components +.. autofunction:: esper.try_component +.. autofunction:: esper.try_components +.. autofunction:: esper.process +.. autofunction:: esper.timed_process +.. autofunction:: esper.clear_database +.. autofunction:: esper.clear_cache +.. autofunction:: esper.clear_dead_entities Events ------ diff --git a/esper/__init__.py b/esper/__init__.py index 8bd0f22..a66bb92 100644 --- a/esper/__init__.py +++ b/esper/__init__.py @@ -464,11 +464,14 @@ def try_components(entity: int, *component_types: _Type[_C]) -> _Optional[_Tuple def clear_dead_entities() -> None: """Finalize deletion of any Entities that are marked as dead. - In the interest of performance, this function duplicates code from the - `delete_entity` function. If that function is changed, those changes should - be duplicated here as well. - This function should be called in main loop after systems. + This function is provided for those who are not making use of + :py:func:`esper.add_processor` and :py:func:`esper.process`. If you are + calling your processors manually, this function should be called in + your main loop after calling all processors. """ + # In the interest of performance, this function duplicates code from the + # `delete_entity` function. If that function is changed, those changes should + # be duplicated here as well. for entity in _dead_entities: for component_type in _entities[entity]: @@ -532,10 +535,19 @@ def delete_world(name: str) -> None: def switch_world(name: str) -> None: - """Switch World contexts. - - This function is used to switch between World contexts. - If the named context does not exist, a new one will be created. + """Switch to a new World context by name. + + Esper can have one or more "Worlds". Each World is a dedicated + context, and does not share Entities, Components, etc. For + some game designs, it simplifies things to use a dedicated + World for each scene. For other designs, a single World may + be sufficient. This function will allow you to create and + switch between as many World contexts as required. If the + requested name does not exist, a new context is created + automatically with that name. + + .. note:: At startup, a "default" context exists, and is + already active. """ if name not in _context_map: # Create a new