Creating an Event

Here I show you how to create an Event and register it for the game to use.

• 1. Writing the Event
• 2. Registering the Event
• 3. Conditions for Events
• 4. Data for Events
• 5. Images for Events
• 6. Changing Stats in Events
• Example

1. Writing the Event

Here I explain, how you write the body of an event. c!pp

Creating an Event follows multiple Step.

Step 1 ist to write the Event itself.

An Event has to follow the following structure:

label event_label (**kwargs):
    $ begin_event(**kwargs);

    // get values

    // get images    

    // dialogue or whatever happens during the event

    // stat changes

    $ end_event('new_daytime', **kwargs)

So the label defines where the event begins.
An event always takes a **kwargs parameter. In it the game delivers all the data and information the game, the event and other functions need to work. So you need to make sure to not overwrite or change values in it haphazardly.

When using the normal value system, to insert data in the event for you to use, there will be no collision since those are stored in a dedicated dict inside the kwargs.

Next is the begin_event method.

This one has to be called at the beginning of each event. This method does a multitude of tasks to prepare and make the event work.

It starts the Gallery_Manager, which is responsible for properly registering the event and all the used values and decisions into the replay gallery.

By adding a version, you can tell the gallery if the stored data about the event is still valid or not. If the version varies from the one used for the data already stored, the gallery wipes the data about the event from the gallery storage. This is necessary if you change the event enough for the data to not be valid anymore. This is the case for example when removing or adding values or changing the order of the values occurence. To get a more detailed explanation, you can look here.

The begin_event method also blocks the player from rolling back further than the start of an event.

At the end of each event we have the end_event method.

This one is also important. This method closes the event. In case of a Composite Event, it calls the next Fragment, in case of the event being played as a replay from the gallery, it returns you to the gallery menu and otherwise it returns you to the game.

By default it returns you to the map but progresses the daytime cycle by one.

By using "new_day", you can skip the entire day and by using anything else or "none", the method simply returns and you can use another way to return to the game or do something else.

It is in your responsibility to have the event return to the game properly when not using the end_event method for returning.

In the next Page I show you how to register the event so it can be used by the game.

2. Registering the Event

Here I show you how to register your eventh{pt .}c!pp, so the game is able to call the event and integrate it into it's systems.

On the last page we created the Event event_label.

Now before registering, we need to decide, where the Event will be stored.

For that the game uses a class called EventStorage. This class registers the events and also provides them when called.
Currently there are 3 types of EventStorage, the EventStorage, the TempEventStorage and the FragmentStorage.
We'll ignore the FragmentStorage for now.

A more detailed explanation of the EventStorages follows in a later chapter.

Now back to the question where we want to register the Event. Tha game has multiple locations, for example the school building, the courtyard and so on. Now each of those locations has three Storages. a general one, a TempEventStorage and a dictionary of multipal EventStorages. The difference between those is, that Events registered in the TempEventStorage will only be shown once and then never again in the playthrough, while Events stored in the normal EventStorage can be shown repeatedly.

When a location is entered by the player, the game will first try to call an event from the TempEventStorage. After that it will try to open an Event from the general EventStorage, and after that it will open a Selection Menu, where the player can select the action he want's to execute. So each action is it's own EventStorage.

In this example, I will register the event for the courtyard, and as it should be shown repeatedly, we use the normal Storage.
So the registration will look like this:

init 1 python: 
    set_current_mod('base')  

    event_label_event = Event(3, "event_label")
    courtyard_events["patrol"].add_event(event_label_event)

So what do we see here. First we open a python block that runs when the game loads. The 1 shows the position in the load order. When registering events, the position should not be lower than 1.

In the second row we set the current mod. This is important for the game to detect from which mod the registrations come from. It is your responsibility to make sure, that when you register content into the game, that you call that method with your mod key at least once at the beginning of each init block. Make sure that the key is identical to the key you provide in the metadata file.

In row 4 we define the event we wrote in the last page of this manual. It is simply built by initializing the Event class with a priority and the renpy label it has to call.

And in row 5 we register the event. As you can see, we add the event into the EventStorage for the patrol action in the courtyard.

With that the event is sucessfully registered and will now be able to be called by the game. But since we added only the barebone of informations, it willl work, but there will be no image in the replay gallery and there is no limitation when it can be called. With that there is always a chance that it can be called.

A list of all Storages can be found here. And how to add your own storages can be found here.

In the next page we will work on how to set conditions and limitations on when an event is allowed to be called.

3. Conditions for Events

Here we talk about Conditions.c!pp 

In this game, Conditions are implemented in a special way. Here the conditions are represented by the Condition-Object. The Condition-Object itself doesn't do much but it serves as base for the different condition types.

The reason Conditions are done this way when fellow coders know there are already boolean operations, is because the conditions have to be checked on demand, so these condition classes help to store the condition and then check on demand if the condition has been fulfilled.

So currently there is a set of different condition types already available. You can find the overview for those here.

So now lets set a condition for our event. On the last Page we used this code to register our event:

init 1 python: 
    set_current_mod('base')  

    event_label_event = Event(3, "event_label")
    courtyard_events["patrol"].add_event(event_label_event)

Now lets add a TimeCondition. The TimeCondition is used to for example set the event to be available only at certain times. For example only on Mondays or only during the evening.

Now the updated code looks like this:

init 1 python: 
    set_current_mod('base')  

    event_label_event = Event(3, "event_label", TimeCondition(day = "5-10", month = "2-", daytime = "f"))
    courtyard_events["patrol"].add_event(event_label_event)

You see now the added TimeCondition. It has multiple input values like day, month and daytime. This condition now limits the availability of the Event to between the 5th and 10th day of the month for only January and Febuary and only during free time. So you see, you have some freedom on what you can set for the TimeCondition. The details on what can be used for this Condition can be found below or in the Condition overview.

TimeCondition(day= "5-10", month = "2-", year = 2024, daytime = "f")

With that we have now successfully limited the Event, so that it now only shows up during certain times and dates.

On the next Page we talk about how to add images to your event.

4. Data for Events

On this page we talk about how we can generate varying datah{pt .}c!pp to the event so it can then use that data to change itself.

This is useful if for example you want to rotate between characters every time the event is called or if you want the event to play out differently after you hit a certain stat limit. Or something else.

To provide this data I created the Selector class. Like the Condition Class, the Selector class is the base from which different Variants can be created. For this example we will put in a RandomListSelector class. This one takes a random value from a set of values. If we put it in the code example from the last pages, it will look like this:

init 1 python: 
    set_current_mod('base')  

    event_label_event = Event(3, "event_label", 
        TimeCondition(day = "5-10", month = "2-", daytime = "f"),
        RandomListSelector("girl", "Aona Komuro", "Lin Kato", "Luna Clark")
    )
    courtyard_events["patrol"].add_event(event_label_event)

Now you see the added Selector. I just put it after the Condition. The order of Conditions and Selectors doesn't matter for it to work, as the Event itself just expects a Set of Conditions or Selectors after the event label. The Event will then filter out the correct classes itself.

A Selector always starts with a key, which is used to identify the value later. In the example above it is "girl". For this Selector it is then followed by all values from which one will be chosen randomly.

One important thing to know is, that after an Event is called, it will then immediately reroll the values for the Selectors. So if you start an event and the Selector returns "Aona Komuro", it will then immediately reroll the value and provide it for the next time the event is called. This is to lower the performance needed for these functions.

Another important thing is, some Selector types can wok with values that have been set by other Selectors. For that to work, the Selectors can only access values from the Selectors above it, since the values are fetched in order from top to bottom.
This also applies to Conditions, since certain Condition Types access the values provided by the Selectors to check if they are fulfilled.
One example is the ValueCondition. It checks if a value for a certain key is identical to the one provided for the Condition. That would look like this:

init 1 python: 
    set_current_mod('base')  

    event_label_event = Event(3, "event_label", 
        TimeCondition(day = "5-10", month = "2-", daytime = "f"),
        RandomListSelector("girl", "Aona Komuro", "Lin Kato", "Luna Clark"),
        ValueCondition("girl", "Lin Kato")
    )
    courtyard_events["patrol"].add_event(event_label_event)

You see it uses the key girl to identify the value and the checks if the value provided by the RandomListSelector is Lin Kato. Only then the Event would be available. As you can also see the Selector is now encased between two Conditions. That again shows that the Conditions and Selectors don't have to be bundled. The order is only important if you want to access the values of other Selectors.

This example now would also prevent the event from ever being shown, since the Event now can only be called when the RandomListSelector randomly picks Lin Kato. Since it only rerolls the value on the first registration and then only when the event is called, the value will never change when the event can't be called. So it is now locked. So it is your responsibility to prevent that from happening unintentionally.

So we added data to the event, now we have to access it in the event itself.

For that the GalleryManager provides the methods get_value and get_level. The main method though is get_value.
Adding it to the event would look like this:

label event_label (**kwargs):
    $ begin_event(**kwargs);

    $ girl = get_value('girl', **kwargs)

    // get images    

    // dialogue or whatever happens during the event

    // stat changes

    $ end_event('new_daytime', **kwargs)

Here I took the event from earlier and added the get_value method. This method does multiple things. For one it retrieves the value behind the key "girl" which we inserted into the Event with the Selector. The other thing this method does is to automatically register the value for the Replay Gallery. In case you play this event as a replay, this method also provides the value you set in the replay menu. 

An important factor here is the order of loading all the values. The order of how you get the values does not have to be the order in how you put the Selector classes in the Event-definition. But the order of the get_value methods is important for the gallery. So if you decide to change the order, you have to register the change with the gallery by providing an updated event version. This tells the gallery that the value order is not valid anymore and thus removes the gallery data for that event. That would look like this:

label event_label (**kwargs):
    $ begin_event(version = "2", **kwargs);

    $ new_girl = get_value('new_girl', **kwargs)
    $ girl = get_value('girl', **kwargs)

    // get images    

    // dialogue or whatever happens during the event

    // stat changes

    $ end_event('new_daytime', **kwargs)

Here you see I added another get_value in front. This would break the gallery data, since it expects the "girl" key and not "new_girl". To tell the gallery, the event has been reworked I added the version argument to begin_event and set the version to 2.
By default the version is set to 1, so it only has to be set when the event undergoes changes that change the order in which the values are loaded. For that reason you only need to change the version when the value order or the value keys change, since it's only the gallery that needs this information.

Now other than the get_value method, there is also the get_level method. This one works a little bit different. The usage is pretty much identical, but this method does not require a Selector in the Event definition. The levels of the school, parents, teachers and secretary are always provided with the data send into the event. So you just call the get_level method together with the correct key for each of the characters. The possible keys are: school_level, parent_level, teacher_level and secretary_level.

In the code it would look like this:

label event_label (**kwargs):
    $ begin_event(**kwargs);

    $ girl = get_value('girl', **kwargs)
    $ school_level = get_level('school_level', **kwargs)

    // get images    

    // dialogue or whatever happens during the event

    // stat changes

    $ end_event('new_daytime', **kwargs)

With that you now have the values defined in the Event definition and are now freely usable in the event.

On the next Page we talk about how to add images to your event.

5. Images for Events

Let's add some images to the event! c!pp

Adding images is very similar to adding values. First we must provide the image for that we have to define a Pattern in the Event definition. The Pattern is define with the Pattern class, which takes a key for identifying the correct pattern and the image pattern. The image pattern is just the path starting from the game folder or in your case starting from the root folder of the mod, with the root folder being the folder where your metadata file is located. The Event definition would then for example look like this:

init 1 python: 
    set_current_mod('base')  

    event_label_event = Event(3, "event_label", 
        TimeCondition(day = "5-10", month = "2-", daytime = "f"),
        RandomListSelector("girl", "Aona Komuro", "Lin Kato", "Luna Clark"),
        Pattern("main", "/images/events/school building/sb_event_4 <school_level> <girl> <step>.webp"),
        Pattern("main2", "/images/events/school building/sb_event_5 <school_level> <girl>.webp", 'school_level', 'girl'),
    )
    courtyard_events["patrol"].add_event(event_label_event)

Here I have added two patterns. First let's look at the Pattern with the key "main".

In Pattern I put "main", which is the key used to identify the correct pattern when showing the images and after that I put in the path, or the pattern. Now I say pattern because you can see in the latter part of the path there are keys put in <>-brackets. school_level, girl_name and step. Now we know girl, since it is defined in the Selector directly above, and we know school_level since it is always present in the event data. step is a new key we haven't seen yet. This key is one of the main functions of these image patterns. The step key is used to create a series of images. 
For example you have 3 images in an event, so you can just name your images "image 1.webp", "image 2.webp" and "image 3.webp". To include all of these images you can use the pattern "/images/.../image <step>.webp" and the method later used to access the images will check what images are available and will then provide them for usage.

In a similar way will the method also replace the keys school_level and girl with the actual values, so the path could then look like this: "/images/events/school building/sb_event_4 1 Aona Komuro <step>.webp". Step is still step since it will then be replaced on demand.

Let's look at the pattern with the key "main2". It is almost identical to the "main"-Pattern except for a little different path, no step key and more keys behind the path. That is another feature these pattern provide. By defining these keys you can set the pattern to also check for images that don't have a value for the corresponding key. The image file would then just have a "#" at the keys position instead. In this example you could have an image named: "sb_event_5 # Aona Komuro 0.webp" or "sb_event_5 1 #.webp" or even "sb_event_5 # #.webp". This is particulary useful if you have images where for this example you don't have any girls in the picture, so instead of having the same image three times just with the different names to conform to all possible value combinations, you can just define one image with "#" for the key.

But please make sure to only use that feature when it is needed. If there is no image with "#", the keys should not be set for ignoring. The method checks for all possible combinations and selects the best one, so while being pretty optimized, it could still have impact on performance.

Now let's use the images in our event. To do that we use the convert_pattern or the show_pattern method.

The difference between these two is that you use convert_pattern for series of images and show_pattern for a single image. In our example we have both, so lets add both. Tha would then look something like this:

label event_label (**kwargs):
    $ begin_event(**kwargs);

    $ image = convert_pattern("main", **kwargs)

    $ show_pattern("main2", **kwargs)
    person "Hi I'm a dialogue text."

    $ image.show(0)
    person "Oh another image."

    $ image.show(1)
    person "Wow such simple"

    // stat changes

    $ end_event('new_daytime', **kwargs)

Here you see I used convert_pattern to get the pattern with the key "main". It is a conversion because that method converts the pattern to an ImageSeries-class. That method comes with a lot of handy functions. One of those is the show method. First things first, the convert_pattern method converts the pattern into an ImageSeries-class and returns it, so I then store it in the image variable so I can use it later. Since it is a series of images defined by the step key inside the pattern, I can show the image with the corresponding step number just by calling "$ image.show(n)" where n is the number of the image. This class can also show videos, but that comes later.

show_pattern does a similar thing, but instead of creating an ImageSeries it just fills the pattern and directly shows the image.

Maybe you already noticed, but the get_value methods are missing here. That is because the convert_pattern and the show_pattern methods retrieve and register those values themselves, so no need to do that again, unless you want to do other things with these values like changing the dialogue.

Another key that can be used for the pattern I haven't talked about yet is the "variant" key. If you add the variant key, you are able to have multiple variants of the same image and the methods will just select one of those at random. You don't have to specify anything. You only have to add the "variant" key to the pattern and the methods check for themselves what variants are available. The only thing you have to make sure is, that you have a series of numbers for that starting with 1, since the method starts looking for the variant "1" and then just goes up until it doesn't find a higher variant number.

If you want to override the variant, you can call the show method with the variant argument like this: "$image.show(0, variant = 1)".

Be aware that the the order where convert_pattern and show_pattern occur in the code and the order in which the keys in the pattern occur is also a factor for the order of data stored in the gallery.

On the last page of this quick manual on how to create an event, I will show you how to manipulate the stats for the different characters.

6. Changing Stats in Events

Let's change some Stats! c!pp

To change stats in the Event there are two methods. one to change stats for the characters and one to change the money.

The first method to change stats for characters in general is change_stats_with_modifier. That one is a label though so it has to be called appropriately. That would look like this:

label event_label (**kwargs):
    $ begin_event(**kwargs);

    $ image = convert_pattern("main", **kwargs)

    $ show_pattern("main2", **kwargs)
    person "Hi I'm a dialogue text."

    $ image.show(0)
    person "Oh another image."

    $ image.show(1)
    person "Wow such simple"

    call change_stats_with_modifier("school",
        happiness = 2, inhibition = TINY)

    $ end_event('new_daytime', **kwargs)

Here you see the change_stats_with_modifer label. First I inserted the key "school" for the character object and after that I added a set of stats with the value on how they should be changed. The Happiness-Stat will be increased by 2 and Inhibition by a tiny amount. 

To add a bit of variety I added keywords that can be used for the stat changes to change the values a little bit randomly. An overview over these keywords can be found in the method description below.

But what is that modifier in the method name? The game has a modifier system, where modifier can be created to change stat changes. This enables you to create buffs or debuffs. The income of the school is also managed by these modifiers. Documentation on how to use them can be found here.

To change the money we use the method change_money_with_modifier. That is is much easier, you just call it and add how you want to change the value. That would look like this:

label event_label (**kwargs):
    $ begin_event(**kwargs);

    $ image = convert_pattern("main", **kwargs)

    $ show_pattern("main2", **kwargs)
    person "Hi I'm a dialogue text."

    $ image.show(0)
    person "Oh another image."

    $ image.show(1)
    person "Wow such simple"

    call change_money_with_modifier(100)

    $ end_event('new_daytime', **kwargs)

I just made it add 100 money.

That is basically everything you need to know to create basic events. Of course you should take a look in the renpy documentation on how to add dialogue, but you can pretty much see it in the examples above or check out the book about dialogue.

The system also has some more advanced stuff which you can find under Advanced Events.

Example

Here is an example on how a full file with the event and its definition could look like.c!pp

init 1 python: 
    set_current_mod('mod')  

    event_label_event = Event(3, "event_label", 
        TimeCondition(day = "5-10", month = "2-", daytime = "f"),
        RandomListSelector("girl", "Aona Komuro", "Lin Kato", "Luna Clark"),
        Pattern("main", "/images/events/school building/sb_event_4 <school_level> <girl> <step>.webp"),
        Pattern("main2", "/images/events/school building/sb_event_5 <school_level> <girl>.webp", 'school_level', 'girl'),
    )
    courtyard_events["patrol"].add_event(event_label_event)

label event_label (**kwargs):
    $ begin_event(**kwargs);

    $ image = convert_pattern("main", **kwargs)

    $ show_pattern("main2", **kwargs)
    person "Hi I'm a dialogue text."

    $ image.show(0)
    person "Oh another image."

    $ image.show(1)
    person "Wow such simple"

    call change_stats_with_modifier("school",
        happiness = 2, inhibition = TINY)

    call change_money_with_modifier(100)

    $ end_event('new_daytime', **kwargs)