Components

If the cave.Scene is where all your game will happen and the cave.Entity is the main class you'll use to build all that, then the cave.Component is the "final piece of the puzzle" that you'll use to customize your Entities as you want and need to. You'll not use the cave.Component alone, but it's important that you understand precisely what it have to offer because this will allow you to understand the entire rest of the Engine and its builtin components.

But most importantly: it will allow you to create your own Components! The main way that Cave Engine is intender to be programmed by you is by creating new Components, that inherits from this cave.Component class and implements its virtual methods. That means that all the methods you'll see here, except the reload one, are virtual and can be overwritten by you as you need.

By the end of this page, you'll find an example of how to create your own Component.

So let's get started!

---

cave.Component

Variables

The component only have one variable: the entity. It stores the cave.Entity owner of the Component. You can't set it to something else (if you try to, it will just ignore what you've done).

entity : cave.Entity

Methods

All the methods above, except the reload one, are meant to be overwritted by you. So feel free to do it so.

Let's start with the basics: When the Entity starts in the scene, it will first call all its Component's start method, so that's the perfect place to initialize your variables and so on. If your component's initialization relies on other Component's initialization, then it's best to use the firstUpdate method as well. After the Entity calls all its component's start method, it will call the firstUpdate.

Important: The Entity is the one who decided whenever to call the firstUpdate method of the components or not and it only calls it before the Entity's first update gets execution internally by the engine code. Meaning that all the Components already in the Entity when it gets created will have this function executed, but after that, even if you reload the Component or add it afterwards, it will not call the Component's firstUpdate anymore.

Here is the Reference API:

start(scene : cave.Scene)
firstUpdate()

Once the component started (after the previous two functions gets called), every frame the Entity will call one of those two methods below, depending if the Scene is paused or not (read the Scene's Documentation for more details). Meaning that this is the perfect place to put your main logic code. Most of the times, what you're looking for is the update method. pausedUpdate only gets called while the scene is paused, as the name suggests and you probably don't want to run Enemy logic on it, as an example.

update()
pausedUpdate()

When the Entity is about to get deleted, it will call all the Component's end method. It also can be called in other situations, such as by the reload method, so keep that in mind. This is a good place to add "shutdown" code, if you have anything to do in it.

end(scene : cave.Scene)

Last but not least, we have the reload method. This one can't be overwritten. It will end(...) the component and then start(..) it again. It's useful because some components like the Mesh and the Light, for optimization purposes, pre cache the data and only changes it during the start.

reload()

---

Creating your own Components

As promised, I'll show you a code example on how to create your own components. The good news is that it's very simple! In fact, if you create a new Python Script in the engine, it will already have this sample code already added for you, so don't worry a lot about it.

Here is a simple code to create own own SuperCustomComponent:

import cave

class SuperCustomComponent(cave.Component):
    def start(self, scene):
        print("I'm alive!")

    def update(self):
        # You can write your update stuff here!
        pass

    def end(self, scene):
        print("Goodbye!")

- Important Note:

You may have noticed that I haven't overwritted the Component's constructor, also known as __init__ by Python. If, for some reason, you decide to have your own __init__ method, you MUST initialize the base cave.Component class and pass the args and kwargs to it, otherwise the Component will not be properly attached to the Entity and it will lead to Undefined Behaviours. Never forget this! Here is how you can do it:

    def __init__(self, *args, **kwargs):
        # Initializing the base class, cave.Component:
        super().__init__(*args, **kwargs)

        # Now you can put your code:
        print("Hello, world!")