2019-01-04T08:35:08Z

Dogeek:

{{AlertInfo|This page was last updated as of Summertime Saga v0.18.0}}

= Modding API =

{{AlertWarn|The API for Summertime Saga is currently under development, and this page is subject to many changes}}

== FSMs (Finite State Machines) ==

FSMs control the flow of the game for a particular character. They are basically linked chains of events (which are called States). The progress is achieved via a Trigger.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:Fsm1.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">''A basic example of a FSM''</div>

=== Creating a FSM ===
Creating a FSM is done in 3 steps :

* Create the states, triggers and a Machine instance, providing the necessary arguments to each constructor. Triggers should be created in an init python block of priority 0 or later.

* Link the states together, with their '''State.add(Trigger t, State next_state)''' method.

* Add all the states to the machine with the '''Machine.add(*State states)''' method.

State and machine definition and state linking should be done in a label named "character_fsm_init", character being the character's name. Additionally, further edits to the machine (such as adding the states) should be done in a label named "character_machine_init", there again, character being the name of the character.

==== Machine specific ====

The Machine constructor has plenty of arguments, here is the detail and what is expected :

:: name : a name for the machine. Is used as a unique identifier for the machine. Will also be used to find the button dialogue for that machine.
:: default_loc : a 4x7 matrix of Locations to be used as the "schedule" for where a given machine should be at any point during the week. A 4x1 or 2x4 matrix may be passed as well, and internally will be converted to a 4x7 matrix. If a 1x4 matrix is passed, it is assumed that the location only varies by time of day, and the day of the week doesn't matter. A 2x4 matrix will split the two, the first 4-list is for weekdays, and the second for weekend days.
:: description, states : (to be deprecated) alternate ways to add states to the machine, and a description that is never used anywhere.
:: vars : A dictionnary containing variables (as strings, the keys of that dictionnary), and init values for those variables. These variables are used with the state actions (see below) and the '''get(string variable)''' and '''set(string variable, object value)''' methods of the Machine class. When a specific state doesn't apply, or you need a variable to change based on the progress with a given path. The "sex speed" variable is assumed to be used only for setting the speed of the animation for sex scenes.

==== State specific ====

At state creation, you may want to add a delay to that state using the delay optional argument. That delay is the number of days until that state is effectively reached once the trigger has been "pulled"

When linking states together, you may want to add '''state actions''' to be executed when the state is triggered. Those actions are as follows :

:: ['set','flag_1'] set's the value of flag_1 to True
:: ['clear','flag_1'] set's the value of flag_1 to False
:: ['toggle','flag_1'] toggle's the value of flag_1 between True and False
:: ['assign',['v1',100]] sets the value of v1 to 100
:: ['inc','v1'] increase the value of v1 by 1
:: ['dec','v1'] decrease the value of v1 by 1
:: ['triggeronzero':['v1',T_a_trigger]] sets v1 -= 1 and if
:::: v1 <= 0 it will fire the Trigger T_a_trigger
:: ['trigger',T_a_trigger], fire the Trigger T_a_trigger
:: ['call','label'], make a RenPy call to label. Label MUST return
:: ['location', [machine, {"tod":tod, "place":place}]], set the forced location for the
:::: machine to place (Moves the NPC). tod is 1-indexed (1=morning, 4=night)
:: ['force', [machine, {"tod": list or int, "flag": 4-list or bool}]]
:::: Says if the location is forced at tod or sets force flags according to the 4-list provided
:: ['unforce', None/machine] unforce the locations for machine or the machine specified forced.
:: ['exec', callable], calls the callable (function or method)
:: ['exec', [callable, *args]], calls the callable and pass in the args specified
:: ['condition', [condition_string, actions_list_true, actions_list_false, (optional) machine]],
:::: executes the actions in actions_list_true
:::: if condition_string evaluates to True, otherwise executes actions_list_false.
:::: conditions lists are assumed to be state actions.
:: ['action', [target_machine, action, target]] Executes the state action on another machine.
:: ['setdefaultloc', <nowiki>[[Location, Location, Location, Location]]</nowiki>] Sets the default locations for the current machine. The argument is in the same format as the default_loc argument in the Machine constructor (1x4, 2x4 or 7x4 matrices)

=== Editing an FSM ===

Editing a currently existing FSM is actually as simple as calling the <code>clear()</code> method of the state you want to clear. It takes one argument, cleardelay, which defaults to False. If cleardelay is True, then the delay of the state will be cleared. If you don't want to edit the state, but just want to clear the delay, you can just set the State.delay attribute to 0 instead.

Once you've cleared the state, the state will be unlinked to the rest of the FSM, which means that story will block at that state, it's then up to you to link that state to the rest of the machine, with addtionnal states in the middle for your code.

=== Using FSMs ===

Using FSMs is suprisingly easy. In your location labels, you can just test the state a Machine is in with the '''is_state(State* states)''' method. Multiple states may be passed in that method, as well as a list of states. If the Machine is in any of the provided states, then the method will return True, and False otherwise. For convenience, other similar methods can be used. '''between_states(State state1, State state2)''' will return True if the Machine is in any state between state1 and state2 but is not in state state2. '''finished_state(State* states)''' will return True if the Machine has finished any of the provided states.

To advance to the next state, the '''trigger(Trigger t)''' method of the Machine class is used. It will advance the Machine to the next state associated with that trigger if the provided trigger is in the current state's table, and won't do anything otherwise.

== Locations ==

Locations handle all the locations in the game. They are represented as a tree, with the possibility of multiple parents (like Smith's Bedroom, which has the frontyard and the hallway as its parents). A required attribute is the location name.

=== Creating a Location ===

Locations are very simple to create. It's as simple as instanciating the Location class, and providing a name for that location to the contructor (which is the only required argument). Locations are mutable, so they should be instantiated in a "modname_locations_init" label.

Furthermore, Locations have several optional arguments :

:: name : the name for that location, as can be seen in the top-left corner of the UI. It's also the way to find and call the relevant location screen, as well as the location label.
:: unlock_popup : the name of a renpy-defined displayable for the popup that should show up when the location is unlocked.
:: background : the name of the background used for that location. The background name must follow several conventions to work properly.
:::: must be in images/backgrounds/
:::: name must start with location_
:::: name must end with _day.jpg. Variants may be made for night (_night.jpg) and evening (_evening.jpg)
:::: if the background is a halloween/christmas background, the strings "_halloween" and "_christmas" must be added before the "_day" (or "_night" etc). This will allow the game to find relevant backgrounds for the time period.
:::: Whatever is leftover should be provided in the background argument of the constructor. The full file path will be constructed by the background (resp. background_blur) properties.
:: parents : either a list of Location or a single Location instance. Will provide the parents of that Location. If left empty, the Location is assumed to be the root of the tree. The root should always be L_map (or L_NULL, but L_NULL should not have children)
:: locked : defaults to False. Whether the Location should be initially locked, and unaccessible at the beginning of the game.
:: label : (to be deprecated) The label name for that location. the formatted_name property will be used later on.

{{underline|'''Example :'''}} <syntaxhighlight lang="Python">L_diane_barn = Location("Diane's Barn", unlock_popup="popup_diane_barn", background="barn_frontyard", parents=L_map, locked=True)</syntaxhighlight> will define a location named "Diane's Barn" (formatted name being dianes_barn), child of L_map, that shows "popup_diane_barn" on unlock, and that is initially locked.

The background is set as barn_frontyard, which means the game will look for files named "backgrounds/location_barn_frontyard_day.jpg" or "backgrounds/location_barn_frontyard_night.jpg" for instance.

== User-defined Screen Actions ==

These screen actions are specific to Summertime Saga, and should be used to keep the flow consistent.

=== MoveTo ===
This action expects a Location to be passed. It will hide the current screen, move the player to that location, and call the corresponding screen as well as jump to the location label

=== BuyItem ===

This action expects an item, or item identifier string to be passed to it. When activated, will buy the item, and show the appropriate failing popups should the transaction fail. Optionally, you may add a callback label with the callback_label optionnal argument. If the transaction succeeds, the game will then call that label (useful if you want some story element to trigger after buying an item).

=== TalkTo ===

To be used to talk to character. Will hide the screen and start the conversation with the given character. It expects a Machine instance, or a string to identify it, in which case it will attempt to find the machine in the store.machines dictionnary.

=== ClearPersistent ===

Will reset the player's persistent data (cookie jar, time spent playing, achievements etc). No arguments expected.

=== GetItem ===

Will get the item, and attempt to show the corresponding popup. No arguments required.

== Items and inventory management ==

The inventory manager is fully automatic, but you may want to add some items to the game. Items are stored in a json file called items.json in the scripts/data/ folder. A typical item definition will look like this :

:: "birth_control_pills": {
:::: "id": "173",
:::: "name": "{b}Birth Control Pills:{/b}",
:::: "cost": "0",
:::: "image": "objects/item_pills3.png",
:::: "description": "Makes you temporarily sterile.",
:::: "closeup": "",
:::: "dialogue_label": "birth_control_pills",
:::: "popup_image": ""
:: }

In order :
* The item identifier.
* The item's id. Unused at this moment.
* The item's name, as seen in the backpack.
* The item's cost. Will be cast as an integer, and will prevent the player from picking up the item if he doesn't have sufficient money.
* The item's miniature image, as seen in the backpack.
* The item's description, as seen in the backpack.
* The item's closeup image, if there is one.
* The item's dialogue label, which will trigger if it exists, on clicking the item. The label should absolutely return, and take an item argument.
* The item's popup image. Shown when first acquiring the item, leave the string empty if there is none.

FUTURE : Put your items in a file named modname_items.json, in a scripts/data folder.

== Game manager class ==

The Game manager class handles everything that is related to the gameplay itself, but is not planned to be extendable by mods. Its methods and attributes are still useable and should be used for your mod.

:: language : a class-level attribute that sets the language of the game, which is used for translations. It defaults to "en" for english with other languages in the game untranslated (like spanish or french for instance)
:: cheat_mode : an attribute that is True if the game is currently in cheat mode (allowing minigames to be skipped)
:: CA_FILE : path to a certification file used to enable requests to websites. Is unused unless the player uses the "allow internet connection" checkbox in the options.
:: lock_ui(), unlock_ui() and ui_locked() : locks, unlocks and returns whether the ui is locked or not (i.e. grayed out)
:: dialog_select(string label_name) : classmethod that will choose a label based on its name and the language class attribute. To be used to split dialogues, and logic, and also allows your mod to be easily translated.
:: choose_label(string template) : classmethod that chooses a label at random that matches the template passed in the arguments.
:: main() : method that is to be called at the end of every label the player jumps to (and not '''called''' to). It calls the player's location screen, and checks for achievements and other stuff. This would be the only method expandable upon. It also clears the return stack, so that traceback are not undigestible. It may take two arguments, clear_return_stack to enable or not return stack clearing, and location, to call the screen of another location than the player's currently in.
:: is_christmas() and is_halloween() : classmethods that will check whether the system clock matches halloween/christmas.

== Player class ==

The Player class handles everything player related. It handles its inventory, grades, vehicle level and stats.
Notable methods :

:: receive_message(string message_id) : player receives a message on the cellphone. Also sets up the alert icon on the UI.
:: has_item(string* items) : checks if the player has any of the items provided at this moment.
:: has_picked_up_item(string* items) : checks if the player has ever picked up any of the items provided.
:: get_item(string item), remove_item(string item) : gets the item, if the item's cost is no higher than the amount of money the player has. Conversely, removes an item by it's string id.
:: get_money(int money) and spend_money(int money) : adds and substract money from the player.
:: has_required_str(int min_str) : checks if the player has the required str (similar for chr, int and dex)
:: go_to(Location location) : goes to the given location.
:: go_to_previous() : goes to the first parent location of the player's current location.
:: increase_str(int amount) : increase the strength by amount. Defaults to 1. Smilar methods exist for int, chr and dex.

== Miscellaneous functions and classes ==

KeepRefs : A class used everywhere to make sure to keep a reference to any object instantiated, making sure '''is''' checks are kept correct.
:: get_instances() : classmethod to get a generator of all the instances of this class' subclass.

LastUpdatedOrderedDict : A dictionnary-like structure that keeps its order, and store its items in the order the keys were last added (and not ''updated''). This is a subclass of Python's OrderedDict from the collections package.
:: listvalues : returns a list of all the values of this dict
:: listkeys : returns a list of all the keys of this dict
:: lastkey : returns the last key added to this dict
:: lastvalue : returns the value of the last key added to this dict
:: isempty : returns whether the dict is empty

format_seconds_to_dhm(int seconds) : returns a formatted string in the form (x)d (y)h (z)m from the number of seconds passed in the arguments.

insert_newlines(string string_to_format, int every) : returns a new string based on the passed in string, with newlines inserted every ''every'' character. ''every'' defaults to 30. Differs from splice_string() in that it will not cut a word in the middle if possible. splice_string() will insert a newline every ''every'' characters without question. insert_newline() is much safer as it will not cut a variable substitution, but is much slower than splice_string.

text_identity(string text) : returns text (unmodified), useful for config.say_menu_text_filter if it is None.

replace_bracket(string text) : returns text without the [ and ] characters (renpy variable formatting syntax).

gauss(float mean, float deviation, float lower, float upper) : returns a random integer number in a normal distribution, clamped between lower and upper.

get_angle_speeds(int angle_width, Iterator angle_range, Iterator speed_range) : returns two lists, true angles and false angles which are lists of tuples (initial_angle, initial_speed) for which the result land in or out of the angle_width. Used in the pregnancy minigame and spin the bottle minigame for instance.

= Hooking into the game =

{{AltertWarn|This feature of the modding API is not complete as of version 0.18.0, the ModManager class is present, but no hooking of any kind can be done at the moment. This message will be deleted once everything is in place}}

== Registration and Enabling of the mod ==

In an init -9 python or later, use the class method "register" of the ModManager class to register your mod to the game.
This registration will make the mod show up in the (upcoming) Mods menu on the main menu of the game. From then, the player may or may not enable the mod for his game.

<syntaxhighlight lang="Python">
init python:
ModManager.register("ikarumod")
</syntaxhighlight>

In the future, it may be necessary to create a manifest file named "modname_manifest.json" in the scripts/data folder. At this point in time, it is unnecessary, as the API is still being under developement.

== Manifest file ==
{{AlertInfo|Not implemented at this time}}

The manifest file will tell the game in which labels your mod should hook into, and which screens. It will also define the name of the main function you wish to use to hook into the game.main() function, if any.

== Screens ==
{{AlertInfo|Not implemented at this time}}

Create your screens with the following convention : modname + _ + in-game screen name (the renpy definition name).
Screens are being included into the main game screens with the use statement. If you wish to add new locations, you'll have to define a screen for it, in which case, you can inspire yourself with the existing screens in the game.

To add the proper background, start with the statement "add player.location.background", which will automatically show the proper background according to the time of day/period of the year. You can then add imagebuttons as you see fit. Please refer to the User-defined screen actions for more information on which screen actions the game defines.

== Labels ==
{{AlertInfo|Not implemented at this time}}

Only "main" labels can be hooked into. Those are labels that end in "$ game.main()"

== Main function ==
{{AlertInfo|Not implemented at this time}}

To hook into the main function, you must register your main function to the ModManager.

<syntaxhighlight lang="Python">
init python:
ModManager.register_main(ikarumod_main)
</syntaxhighlight>

In the above example, ikarumod_main is assumed to be a callable, which should be a python function. This function will be called with no arguments at the end of the game.main() method.

Hooking into the main function is usually useful for code you want executed every time the game returns to a main screen, i.e. at the end of location labels for instance. This is where you can repeatedly check if the condition for an achievement has been fulfilled. If the provided function is not a callable, a ModLoaderError exception will be raised.

= Imported modules and directory structure =

== Third-party modules ==

=== Platform agnostic ===
:: os
:: pygame
:: sys
:: from time : time, clock
:: from copy : copy, deepcopy
:: datetime
:: re
:: random
:: math
:: from collections : defaultdict, OrderedDict and Counter
:: weakref
:: codecs
:: hashlib
:: json
:: itertools
:: operator
:: textwrap
:: deuces

=== Desktop builds ===
:: certifi
:: requests

=== Mobile builds ===
:: android
:: pyjnius

== Directory Structure ==

:: game
:::: audio
:::: fonts
:::: images
:::::: achievements
:::::: backgrounds
:::::: boxes
:::::: buttons
:::::: cellphone
:::::: characters
:::::: map
:::::: objects
:::::: vfx
:::: python-packages
:::: scripts
:::::: characters
:::::::: One folder for each character, containing an fsm file, a character.rpy file for misc stuff, and a layeredimage definition file. May contain a file for the character's button and the according dialogues.
:::::: core
:::::::: core files are put there, mostly what has been documented in the Modding API section of this manifesto.
:::::: data
:::::::: JSON files that contain data about the game. Stuff like items, achievements, keymap or text messages are defined here.
:::::: defines
:::::::: General image definitions, transforms etc.
:::::: locations
:::::::: One folder for every location, sorted in a tree-like structure. Each location has a main file, a screen file and a dialogues file
:::::: minigames
:::::::: One folder for every minigame, the minigame dialogues and screen files are in that folder.
:::::: script.rpy
:::::: pregnancy_announcements.rpy
:::: changelog.txt
:::: pledge_list.txt

Modding

2019-01-04T08:34:27Z

Dogeek:

{{AlertInfo|This page was last updated as of Summertime Saga v0.18.0}}

= Modding API =

{{AlertWarn|The API for Summertime Saga is currently under development, and this page is subject to many changes}}

== FSMs (Finite State Machines) ==

FSMs control the flow of the game for a particular character. They are basically linked chains of events (which are called States). The progress is achieved via a Trigger.

<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">[[File:Fsm1.png]]</div>
<div class="center" style="width: auto; margin-left: auto; margin-right: auto;">''A basic example of a FSM''</div>

=== Creating a FSM ===
Creating a FSM is done in 3 steps :

* Create the states, triggers and a Machine instance, providing the necessary arguments to each constructor. Triggers should be created in an init python block of priority 0 or later.

* Link the states together, with their '''State.add(Trigger t, State next_state)''' method.

* Add all the states to the machine with the '''Machine.add(*State states)''' method.

State and machine definition and state linking should be done in a label named "character_fsm_init", character being the character's name. Additionally, further edits to the machine (such as adding the states) should be done in a label named "character_machine_init", there again, character being the name of the character.

==== Machine specific ====

The Machine constructor has plenty of arguments, here is the detail and what is expected :

:: name : a name for the machine. Is used as a unique identifier for the machine. Will also be used to find the button dialogue for that machine.
:: default_loc : a 4x7 matrix of Locations to be used as the "schedule" for where a given machine should be at any point during the week. A 4x1 or 2x4 matrix may be passed as well, and internally will be converted to a 4x7 matrix. If a 1x4 matrix is passed, it is assumed that the location only varies by time of day, and the day of the week doesn't matter. A 2x4 matrix will split the two, the first 4-list is for weekdays, and the second for weekend days.
:: description, states : (to be deprecated) alternate ways to add states to the machine, and a description that is never used anywhere.
:: vars : A dictionnary containing variables (as strings, the keys of that dictionnary), and init values for those variables. These variables are used with the state actions (see below) and the '''get(string variable)''' and '''set(string variable, object value)''' methods of the Machine class. When a specific state doesn't apply, or you need a variable to change based on the progress with a given path. The "sex speed" variable is assumed to be used only for setting the speed of the animation for sex scenes.

==== State specific ====

At state creation, you may want to add a delay to that state using the delay optional argument. That delay is the number of days until that state is effectively reached once the trigger has been "pulled"

When linking states together, you may want to add '''state actions''' to be executed when the state is triggered. Those actions are as follows :

:: ['set','flag_1'] set's the value of flag_1 to True
:: ['clear','flag_1'] set's the value of flag_1 to False
:: ['toggle','flag_1'] toggle's the value of flag_1 between True and False
:: ['assign',['v1',100]] sets the value of v1 to 100
:: ['inc','v1'] increase the value of v1 by 1
:: ['dec','v1'] decrease the value of v1 by 1
:: ['triggeronzero':['v1',T_a_trigger]] sets v1 -= 1 and if
:::: v1 <= 0 it will fire the Trigger T_a_trigger
:: ['trigger',T_a_trigger], fire the Trigger T_a_trigger
:: ['call','label'], make a RenPy call to label. Label MUST return
:: ['location', [machine, {"tod":tod, "place":place}]], set the forced location for the
:::: machine to place (Moves the NPC). tod is 1-indexed (1=morning, 4=night)
:: ['force', [machine, {"tod": list or int, "flag": 4-list or bool}]]
:::: Says if the location is forced at tod or sets force flags according to the 4-list provided
:: ['unforce', None/machine] unforce the locations for machine or the machine specified forced.
:: ['exec', callable], calls the callable (function or method)
:: ['exec', [callable, *args]], calls the callable and pass in the args specified
:: ['condition', [condition_string, actions_list_true, actions_list_false, (optional) machine]],
:::: executes the actions in actions_list_true
:::: if condition_string evaluates to True, otherwise executes actions_list_false.
:::: conditions lists are assumed to be state actions.
:: ['action', [target_machine, action, target]] Executes the state action on another machine.
:: ['setdefaultloc', <nowiki>[[Location, Location, Location, Location]]</nowiki>] Sets the default locations for the current machine. The argument is in the same format as the default_loc argument in the Machine constructor (1x4, 2x4 or 7x4 matrices)

=== Editing an FSM ===

Editing a currently existing FSM is actually as simple as calling the <code>clear()</code> method of the state you want to clear. It takes one argument, cleardelay, which defaults to False. If cleardelay is True, then the delay of the state will be cleared. If you don't want to edit the state, but just want to clear the delay, you can just set the State.delay attribute to 0 instead.

Once you've cleared the state, the state will be unlinked to the rest of the FSM, which means that story will block at that state, it's then up to you to link that state to the rest of the machine, with addtionnal states in the middle for your code.

=== Using FSMs ===

Using FSMs is suprisingly easy. In your location labels, you can just test the state a Machine is in with the '''is_state(State* states)''' method. Multiple states may be passed in that method, as well as a list of states. If the Machine is in any of the provided states, then the method will return True, and False otherwise. For convenience, other similar methods can be used. '''between_states(State state1, State state2)''' will return True if the Machine is in any state between state1 and state2 but is not in state state2. '''finished_state(State* states)''' will return True if the Machine has finished any of the provided states.

To advance to the next state, the '''trigger(Trigger t)''' method of the Machine class is used. It will advance the Machine to the next state associated with that trigger if the provided trigger is in the current state's table, and won't do anything otherwise.

== Locations ==

Locations handle all the locations in the game. They are represented as a tree, with the possibility of multiple parents (like Smith's Bedroom, which has the frontyard and the hallway as its parents). A required attribute is the location name.

=== Creating a Location ===

Locations are very simple to create. It's as simple as instanciating the Location class, and providing a name for that location to the contructor (which is the only required argument). Locations are mutable, so they should be instantiated in a "modname_locations_init" label.

Furthermore, Locations have several optional arguments :

:: name : the name for that location, as can be seen in the top-left corner of the UI. It's also the way to find and call the relevant location screen, as well as the location label.
:: unlock_popup : the name of a renpy-defined displayable for the popup that should show up when the location is unlocked.
:: background : the name of the background used for that location. The background name must follow several conventions to work properly.
:::: must be in images/backgrounds/
:::: name must start with location_
:::: name must end with _day.jpg. Variants may be made for night (_night.jpg) and evening (_evening.jpg)
:::: if the background is a halloween/christmas background, the strings "_halloween" and "_christmas" must be added before the "_day" (or "_night" etc). This will allow the game to find relevant backgrounds for the time period.
:::: Whatever is leftover should be provided in the background argument of the constructor. The full file path will be constructed by the background (resp. background_blur) properties.
:: parents : either a list of Location or a single Location instance. Will provide the parents of that Location. If left empty, the Location is assumed to be the root of the tree. The root should always be L_map (or L_NULL, but L_NULL should not have children)
:: locked : defaults to False. Whether the Location should be initially locked, and unaccessible at the beginning of the game.
:: label : (to be deprecated) The label name for that location. the formatted_name property will be used later on.

{{underline|'''Example :'''}} <syntaxhighlight lang="Python">L_diane_barn = Location("Diane's Barn", unlock_popup="popup_diane_barn", background="barn_frontyard", parents=L_map, locked=True)</syntaxhighlight> will define a location named "Diane's Barn" (formatted name being dianes_barn), child of L_map, that shows "popup_diane_barn" on unlock, and that is initially locked.

The background is set as barn_frontyard, which means the game will look for files named "backgrounds/location_barn_frontyard_day.jpg" or "backgrounds/location_barn_frontyard_night.jpg" for instance.

== User-defined Screen Actions ==

These screen actions are specific to Summertime Saga, and should be used to keep the flow consistent.

=== MoveTo ===
This action expects a Location to be passed. It will hide the current screen, move the player to that location, and call the corresponding screen as well as jump to the location label

=== BuyItem ===

This action expects an item, or item identifier string to be passed to it. When activated, will buy the item, and show the appropriate failing popups should the transaction fail. Optionally, you may add a callback label with the callback_label optionnal argument. If the transaction succeeds, the game will then call that label (useful if you want some story element to trigger after buying an item).

=== TalkTo ===

To be used to talk to character. Will hide the screen and start the conversation with the given character. It expects a Machine instance, or a string to identify it, in which case it will attempt to find the machine in the store.machines dictionnary.

=== ClearPersistent ===

Will reset the player's persistent data (cookie jar, time spent playing, achievements etc). No arguments expected.

=== GetItem ===

Will get the item, and attempt to show the corresponding popup. No arguments required.

== Items and inventory management ==

The inventory manager is fully automatic, but you may want to add some items to the game. Items are stored in a json file called items.json in the scripts/data/ folder. A typical item definition will look like this :

:: "birth_control_pills": {
:::: "id": "173",
:::: "name": "{b}Birth Control Pills:{/b}",
:::: "cost": "0",
:::: "image": "objects/item_pills3.png",
:::: "description": "Makes you temporarily sterile.",
:::: "closeup": "",
:::: "dialogue_label": "birth_control_pills",
:::: "popup_image": ""
:: }

In order :
* The item identifier.
* The item's id. Unused at this moment.
* The item's name, as seen in the backpack.
* The item's cost. Will be cast as an integer, and will prevent the player from picking up the item if he doesn't have sufficient money.
* The item's miniature image, as seen in the backpack.
* The item's description, as seen in the backpack.
* The item's closeup image, if there is one.
* The item's dialogue label, which will trigger if it exists, on clicking the item. The label should absolutely return, and take an item argument.
* The item's popup image. Shown when first acquiring the item, leave the string empty if there is none.

FUTURE : Put your items in a file named modname_items.json, in a scripts/data folder.

== Game manager class ==

The Game manager class handles everything that is related to the gameplay itself, but is not planned to be extendable by mods. Its methods and attributes are still useable and should be used for your mod.

:: language : a class-level attribute that sets the language of the game, which is used for translations. It defaults to "en" for english with other languages in the game untranslated (like spanish or french for instance)
:: cheat_mode : an attribute that is True if the game is currently in cheat mode (allowing minigames to be skipped)
:: CA_FILE : path to a certification file used to enable requests to websites. Is unused unless the player uses the "allow internet connection" checkbox in the options.
:: lock_ui(), unlock_ui() and ui_locked() : locks, unlocks and returns whether the ui is locked or not (i.e. grayed out)
:: dialog_select(string label_name) : classmethod that will choose a label based on its name and the language class attribute. To be used to split dialogues, and logic, and also allows your mod to be easily translated.
:: choose_label(string template) : classmethod that chooses a label at random that matches the template passed in the arguments.
:: main() : method that is to be called at the end of every label the player jumps to (and not '''called''' to). It calls the player's location screen, and checks for achievements and other stuff. This would be the only method expandable upon. It also clears the return stack, so that traceback are not undigestible. It may take two arguments, clear_return_stack to enable or not return stack clearing, and location, to call the screen of another location than the player's currently in.
:: is_christmas() and is_halloween() : classmethods that will check whether the system clock matches halloween/christmas.

== Player class ==

The Player class handles everything player related. It handles its inventory, grades, vehicle level and stats.
Notable methods :

:: receive_message(string message_id) : player receives a message on the cellphone. Also sets up the alert icon on the UI.
:: has_item(string* items) : checks if the player has any of the items provided at this moment.
:: has_picked_up_item(string* items) : checks if the player has ever picked up any of the items provided.
:: get_item(string item), remove_item(string item) : gets the item, if the item's cost is no higher than the amount of money the player has. Conversely, removes an item by it's string id.
:: get_money(int money) and spend_money(int money) : adds and substract money from the player.
:: has_required_str(int min_str) : checks if the player has the required str (similar for chr, int and dex)
:: go_to(Location location) : goes to the given location.
:: go_to_previous() : goes to the first parent location of the player's current location.
:: increase_str(int amount) : increase the strength by amount. Defaults to 1. Smilar methods exist for int, chr and dex.

== Miscellaneous functions and classes ==

KeepRefs : A class used everywhere to make sure to keep a reference to any object instantiated, making sure '''is''' checks are kept correct.
:: get_instances() : classmethod to get a generator of all the instances of this class' subclass.

LastUpdatedOrderedDict : A dictionnary-like structure that keeps its order, and store its items in the order the keys were last added (and not ''updated''). This is a subclass of Python's OrderedDict from the collections package.
:: listvalues : returns a list of all the values of this dict
:: listkeys : returns a list of all the keys of this dict
:: lastkey : returns the last key added to this dict
:: lastvalue : returns the value of the last key added to this dict
:: isempty : returns whether the dict is empty

format_seconds_to_dhm(int seconds) : returns a formatted string in the form (x)d (y)h (z)m from the number of seconds passed in the arguments.

insert_newlines(string string_to_format, int every) : returns a new string based on the passed in string, with newlines inserted every ''every'' character. ''every'' defaults to 30. Differs from splice_string() in that it will not cut a word in the middle if possible. splice_string() will insert a newline every ''every'' characters without question. insert_newline() is much safer as it will not cut a variable substitution, but is much slower than splice_string.

text_identity(string text) : returns text (unmodified), useful for config.say_menu_text_filter if it is None.

replace_bracket(string text) : returns text without the [ and ] characters (renpy variable formatting syntax).

gauss(float mean, float deviation, float lower, float upper) : returns a random integer number in a normal distribution, clamped between lower and upper.

get_angle_speeds(int angle_width, Iterator angle_range, Iterator speed_range) : returns two lists, true angles and false angles which are lists of tuples (initial_angle, initial_speed) for which the result land in or out of the angle_width. Used in the pregnancy minigame and spin the bottle minigame for instance.

= Hooking into the game =

{{AltertWarn|This feature of the modding API is not complete as of version 0.18.0, the ModManager class is present, but no hooking of any kind can be done at the moment. This message will be deleted once everything is in place}}

== Registration and Enabling of the mod ==

In an init -9 python or later, use the class method "register" of the ModManager class to register your mod to the game.
This registration will make the mod show up in the (upcoming) Mods menu on the main menu of the game. From then, the player may or may not enable the mod for his game.

<syntaxhighlight lang="Python">
init python:
ModManager.register("ikarumod")
</syntaxhighlight>

In the future, it may be necessary to create a manifest file named "modname_manifest.json" in the scripts/data folder. At this point in time, it is unnecessary, as the API is still being under developement.

== Manifest file ==
{{AltertInfo|Not implemented at this time}}

The manifest file will tell the game in which labels your mod should hook into, and which screens. It will also define the name of the main function you wish to use to hook into the game.main() function, if any.

== Screens ==
{{AltertInfo|Not implemented at this time}}

Create your screens with the following convention : modname + _ + in-game screen name (the renpy definition name).
Screens are being included into the main game screens with the use statement. If you wish to add new locations, you'll have to define a screen for it, in which case, you can inspire yourself with the existing screens in the game.

To add the proper background, start with the statement "add player.location.background", which will automatically show the proper background according to the time of day/period of the year. You can then add imagebuttons as you see fit. Please refer to the User-defined screen actions for more information on which screen actions the game defines.

== Labels ==
{{AltertInfo|Not implemented at this time}}

Only "main" labels can be hooked into. Those are labels that end in "$ game.main()"

== Main function ==
{{AltertInfo|Not implemented at this time}}

To hook into the main function, you must register your main function to the ModManager.

<syntaxhighlight lang="Python">
init python:
ModManager.register_main(ikarumod_main)
</syntaxhighlight>

In the above example, ikarumod_main is assumed to be a callable, which should be a python function. This function will be called with no arguments at the end of the game.main() method.

Hooking into the main function is usually useful for code you want executed every time the game returns to a main screen, i.e. at the end of location labels for instance. This is where you can repeatedly check if the condition for an achievement has been fulfilled. If the provided function is not a callable, a ModLoaderError exception will be raised.

= Imported modules and directory structure =

== Third-party modules ==

=== Platform agnostic ===
:: os
:: pygame
:: sys
:: from time : time, clock
:: from copy : copy, deepcopy
:: datetime
:: re
:: random
:: math
:: from collections : defaultdict, OrderedDict and Counter
:: weakref
:: codecs
:: hashlib
:: json
:: itertools
:: operator
:: textwrap
:: deuces

=== Desktop builds ===
:: certifi
:: requests

=== Mobile builds ===
:: android
:: pyjnius

== Directory Structure ==

:: game
:::: audio
:::: fonts
:::: images
:::::: achievements
:::::: backgrounds
:::::: boxes
:::::: buttons
:::::: cellphone
:::::: characters
:::::: map
:::::: objects
:::::: vfx
:::: python-packages
:::: scripts
:::::: characters
:::::::: One folder for each character, containing an fsm file, a character.rpy file for misc stuff, and a layeredimage definition file. May contain a file for the character's button and the according dialogues.
:::::: core
:::::::: core files are put there, mostly what has been documented in the Modding API section of this manifesto.
:::::: data
:::::::: JSON files that contain data about the game. Stuff like items, achievements, keymap or text messages are defined here.
:::::: defines
:::::::: General image definitions, transforms etc.
:::::: locations
:::::::: One folder for every location, sorted in a tree-like structure. Each location has a main file, a screen file and a dialogues file
:::::: minigames
:::::::: One folder for every minigame, the minigame dialogues and screen files are in that folder.
:::::: script.rpy
:::::: pregnancy_announcements.rpy
:::: changelog.txt
:::: pledge_list.txt

Modding

2019-01-02T07:21:22Z

Dogeek: