### Stellaris Script Extender: Game Start Cleanup Event

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/events/notai_ssex_generic_events.txt

This event (`ssex_setup.1`) is triggered immediately upon game start. Its primary purpose is to fire the `on_game_start_begin` on-action, which is crucial for game initialization routines. Additionally, it performs cleanup of old global event country targets, ensuring compatibility with vanilla game mechanics and preventing issues from previous sessions by removing any lingering `global_event_country` instances.

```Stellaris Script
event = {
	id = ssex_setup.1
	is_triggered_only = yes
	hide_window = yes
	immediate = {
		fire_on_action = { on_action = on_game_start_begin }
		if = {
			limit = { exists = event_target:global_event_country }
			clear_global_event_target = global_event_country
		}
		every_country = {
			limit = { is_country_type = global_event }
			destroy_country = yes
		}
	}
}
```

--------------------------------

### Define Events on Game Start Begin (Early Initialization)

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/on_actions/!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!notai_ssex_priority.txt

Registers events that run at the very beginning of game initialization, even before vanilla game setup. This is a critical phase for early modifications, but requires careful handling as game targets like `global_event_country` may not yet be available or stable and will be overwritten later.

```Stellaris Script
# This = Nothing
### NOTE: THIS IS CALLED BEFORE ANY VANILLA INIT IS DONE
### event_target:global_event_country DOES NOT EXIST YET AND WILL BE OVERWRITTEN AFTER THIS CALL TO KEEP THE GAME FUNCTIONAL
on_game_start_begin = {
	events = {
		ssex_mod_auto_update.0
	}
}
```

--------------------------------

### Define Events on Game Start

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/on_actions/!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!notai_ssex_priority.txt

Registers a set of events to be triggered immediately when the game starts. These events typically handle initial setup procedures for the Stellaris Script Extender, ensuring core functionalities are initialized.

```Stellaris Script
on_game_start = {
	events = {
		ssex_setup.0
		ssex_setup.1
	}
}
```

--------------------------------

### Define Stellaris Keyboard Setup Event

Source: https://github.com/oldent/stellaris-script-extender/blob/main/keyboard/events/notai_ssex_keyboard_setup.txt

This script defines a specific event within the Stellaris game engine. The 'ssex_keyboard_setup.0' event is configured to be triggered only by other game logic, remains hidden from the player's view, and immediately calls a helper function 'ssex_ensure_string_dictionary_exists' to prepare necessary data structures for keyboard-related operations.

```Stellaris Script
namespace = ssex_keyboard_setup

event = {
	id = ssex_keyboard_setup.0
	is_triggered_only = yes
	hide_window = yes
	immediate = {
		ssex_ensure_string_dictionary_exists = yes
	}
}
```

--------------------------------

### API: Get or Create Database (PDS Script)

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_database_effects.txt

This API describes the `ssex_get_database` effect, which retrieves an existing database or creates a new one if it doesn't exist. It supports both globally identified databases and databases bound to a specific scope.

```APIDOC
ssex_get_database:
  description: Retrieves an existing database and creates one if it does not exist.
  parameters:
    - name: identifier
      type: string
      optional: true
      description: The unique identifier of this database, used for global databases.
    - name: bound_to
      type: scope
      optional: true
      description: The scope this database is bound to, used for scope specific variables.
```

--------------------------------

### Define on_game_start_begin Event for Stellaris Script Extender

Source: https://github.com/oldent/stellaris-script-extender/blob/main/keyboard/common/on_actions/notai_ssex_keyboard_actions.txt

This snippet defines the `on_game_start_begin` event, a special trigger point in Stellaris modding that executes at the earliest stage of game startup, prior to the application of any default game values. It is used here to call the `ssex_keyboard_setup.0` event, which likely initializes custom keyboard bindings or other mod-specific configurations.

```Stellaris Scripting Language
# Called before vanilla setup values
on_game_start_begin = {
	events = {
		ssex_keyboard_setup.0
	}
}
```

--------------------------------

### Stellaris Script: Get or Create Database

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_database_effects.txt

This Stellaris Script function retrieves an existing database or creates a new one if it doesn't exist. It validates input parameters 'identifier' or 'bound_to' to ensure a database can be managed. The function saves the owner scope and then attempts to get the database; if not found, it creates a new one. The database reference is returned via `event_target:ssex_return_value`.

```Stellaris Script
ssex_get_or_create_database = {
	[[identifier]set_global_flag = ssex_param_one_activated]
	[[bound_to]set_global_flag = ssex_param_two_activated]
	if = {
		limit = {
			NOR = {
				has_global_flag = ssex_param_one_activated
				has_global_flag = ssex_param_two_activated
			}
		}
		log_error = "ssex_get_or_create_database: Neither parameters identifier or bound_to are fulfilled, a database lacking both parameters cannot be managed or found once all scopes point away from it."
		break = yes
	}
	else = {
		remove_global_flag = ssex_param_one_activated
		remove_global_flag = ssex_param_two_activated
	}
	[[bound_to]
		if = {
			limit = { is_scope_set = $bound_to$ }
			save_global_event_target_as = ssex_hidden_database_owner_scope
		}
		elssex_if = {
			limit = { is_scope_set = event_target:$bound_to$ }
			save_global_event_target_as = ssex_hidden_database_owner_scope
		}
		else = {
			log_error = "ssex_get_or_create_database: Invalid scope reference passed by argument: bound_to"
			break = yes
		}
	]
	ssex_clear_return_value = yes
	ssex_get_database = {
		[[identifier]identifier = $identifier$]
		[[bound_to]bound_to = event_target:ssex_hidden_database_owner_scope]
	}
	if = {
		limit = { NOT = { exists = event_target:ssex_return_value } }
		event_target:ssex_hidden_database_owner_scope = {
			ssex_create_database = {
				[[identifier]identifier = $identifier$]
				[[bound_to]bound_to = event_target:ssex_hidden_database_owner_scope]
			}
		}
	}
}
```

--------------------------------

### Stellaris Script Extender: Library Initialization Event

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/events/notai_ssex_generic_events.txt

This event (`ssex_setup.0`) is triggered only once to initialize the Stellaris Script Extender (SSEX) library. It sets a global flag indicating the mod is enabled, creates a special 'database' species to hold global event targets, initializes a global database, and sets up a private event country for internal use. It ensures the core SSEX infrastructure is in place for subsequent operations.

```Stellaris Script
event = {
	id = ssex_setup.0
	is_triggered_only = yes
	hide_window = yes
	trigger = { NOT = { exists = event_target:ssex_global_event_database } }
	immediate = {
		set_global_flag = script_extender_enabled
		create_species = {
			name = ssex_database_species_name
			class = MACHINE
			traits = {}
			effect = { ssex_save_global_event_target_as = { event_target_name = ssex_database_entry_species } }
		}
		ssex_create_database = yes
		event_target:ssex_last_created_database = {
			set_variable = {
				which = ssex_global_database_count
				value = 1
			}
			ssex_set_database_flag = { flag = ssex_global_database }
			ssex_save_global_event_target_as = { event_target_name = ssex_global_database }
		}
		ssex_create_event_country = { identifier = ssex_private_event_country }
		event_target:ssex_return_value = { ssex_save_global_event_target_as = { event_target_name = ssex_event_country } }
		ssex_clear_return_value = yes
	}
}
```

--------------------------------

### Stellaris Script: Set Keyboard Cursor to Start of Input

Source: https://github.com/oldent/stellaris-script-extender/blob/main/keyboard/events/notai_ssex_keyboard_main.txt

This option handles the down arrow key, setting the keyboard's current index to 0. This effectively moves the cursor to the beginning of the input string.

```Stellaris Script
option = {
	name = ssex_key_down_arrow
	#custom_gui = ""
	is_dialog_only = yes
	responssex_text = ssex_keyboard_desc
	hidden_effect = {
		set_variable = {
			which = ssex_keyboard_current_index
			value = 0
		}
	}
}
```

--------------------------------

### Dump Stellaris Scope Information for Debugging

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

This effect is designed for debugging purposes. It forces an 'unsupported scope' error, which in turn triggers a complete log dump of existing scopes, their types, and scope chains. This can be invaluable for understanding the current game state and debugging complex script interactions.

```Stellaris Script
ssex_dump_scopes_effect = {
	if = {
		limit = { is_scope_type = country }
		set_planet_flag = dump_scopes
	}
	else = { set_country_flag = dump_scopes }
}
```

--------------------------------

### Stellaris Script: Configure Random Number Generation Variables

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

This Stellaris Script block defines the `ssex_random_variable` structure, which initializes and configures parameters for a random number generation system. It processes optional `min`, `max`, and `decimals` inputs, adjusting decimal precision and calculating internal multipliers (`ssex_rng_max_mult`) to ensure correct random number generation within specified bounds and precision. The script includes logic to cap decimal places, determine precision from input min/max values if not explicitly set, and handle edge cases for variable initialization.

```Stellaris Script
ssex_random_variable = {
	set_variable = {
		which = ssex_rng_number_min
		value = $min|0$
	}
	set_variable = {
		which = ssex_rng_number_max
		value = $max|100$
	}
	set_variable = {
		which = ssex_rng_decimal_places
	
```

--------------------------------

### APIDOC: Generate Random Number and Assign to Variable

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

This effect generates a random number and assigns it to a specified variable. It provides optional parameters to control the precision of decimal places and the minimum value of the generated number. The minimum value can be a static number or another variable within the same scope.

```APIDOC
Effect: ssex_create_random_number_effect
Parameters:
  variable: string - The name of the variable to randomize.
  decimals: integer (Optional) - The minimum amount of decimal places for the random number (defaults to 0).
  min: number/variable (Optional) - The minimum value of the variable. Can be a variable in the same scope or a static number (defaults to 0).
```

--------------------------------

### Stellaris Script Extender: Mod Version Registration Event

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/events/notai_ssex_generic_events.txt

This event (`ssex_mod_auto_update.0`) is a key component of the SSEX mod auto-update system. It is triggered only if the `ssex_mod_update_enabled` global flag is set, indicating that the auto-update feature is active. Its sole action is to fire the `on_ssex_register_mod_version` on-action, which handles the registration of the mod's current version upon game load, facilitating version tracking and potential updates.

```Stellaris Script
event = {
	id = ssex_mod_auto_update.0
	is_triggered_only = yes
	hide_window = yes
	trigger = { has_global_flag = ssex_mod_update_enabled }
	immediate = {
		fire_on_action = { on_action = on_ssex_register_mod_version }
	}
}
```

--------------------------------

### Get Stellaris Event Country by ID

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

This script retrieves an event country based on its unique identifier. It searches for a country of type `ssex_country_event` that has the specified flag. The found country is then saved to `event_target:ssex_return_value` for subsequent access.

```Stellaris Script
ssex_get_event_country = {
	random_country = {
		limit = {
			is_country_type = ssex_country_event
			has_country_flag = $identifier$
		}
		if = {
			limit = { exists = event_target:ssex_return_value }
			clear_global_event_target = ssex_return_value
		}
		save_global_event_target_as = ssex_return_value
	}
}
```

--------------------------------

### API: Create and Add List Entry to Database

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

This API documentation describes the parameters required for a function or script that creates and adds a new list entry to an existing database. It specifies a mandatory unique identifier for the list and an optional index for placement.

```APIDOC
Function: Creates and adds a list entry to a database
Parameters:
  identifier: string - A database unique identifier for the list (required)
  index: integer (optional) - The index for where to add the given list entry on the list, default value is count - 1
```

--------------------------------

### Decrement Stellaris Script Variable

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

The `ssex_decrement` function allows for decreasing the value of a specified variable by one. It's useful for managing resource counts or countdowns in Stellaris script logic.

```Stellaris Script
ssex_decrement = {
	subtract_variable = {
		which = $variable$
		value = 1
	}
}
```

```APIDOC
ssex_decrement:
  Parameters:
    variable: The name of the variable to decrement.
```

--------------------------------

### Test Global Database Creation, Retrieval, and Deletion

Source: https://github.com/oldent/stellaris-script-extender/blob/main/test/events/ssex_test_databases.txt

This Stellaris script defines a country event (`ssex_database_test.0`) to thoroughly test the creation, retrieval, and deletion of a global database object identified by `ssex_test_global_database_object`. It uses `init_assert` and `assert_scope_exists`/`assert_scope_not_exists` to validate each step, ensuring the database functions correctly.

```Stellaris Script
namespace = ssex_database_test

country_event = {
	id = ssex_database_test.0
	is_triggered_only = yes
	hide_window = yes

	trigger = {}

	immediate = {
		init_assert = yes
		ssex_clear_return_value = yes
		ssex_get_database = { identifier = ssex_test_global_database_object }
		assert_scope_not_exists = { SCOPE = event_target:ssex_return_value }
		if = {
			limit = { assert_passed = yes }
			log_error = "Called Line"
			ssex_create_database = { identifier = ssex_test_global_database_object }
			assert_scope_exists = { SCOPE = event_target:ssex_return_value }
		}
		if = {
			limit = { assert_passed = yes }
			log_error = "Called Line"
			ssex_clear_return_value = yes
			ssex_get_database = { identifier = ssex_test_global_database_object }
			assert_scope_exists = { SCOPE = event_target:ssex_return_value }
		}
		if = {
			limit = { assert_passed = yes }
			log_error = "Called Line"
			ssex_delete_database = { identifier = ssex_test_global_database_object }
			ssex_get_database = { identifier = ssex_test_global_database_object }
			assert_scope_not_exists = { SCOPE = event_target:ssex_return_value }
		}
		if = {
			limit = { assert_passed = yes }
			log_error = "ssex_database_test.0 passed all tests"
		}
	}
}
```

--------------------------------

### Define Events for Mod Version Registration

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/on_actions/!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!notai_ssex_priority.txt

Placeholder for events that would be triggered when the Stellaris Script Extender attempts to register the mod's version. Currently, no specific events are defined for this trigger, indicating it might be reserved for future functionality or handled elsewhere.

```Stellaris Script
on_ssex_register_mod_version = {
	events = {
		
	}
}
```

--------------------------------

### API Reference: ssex_add_entry_to_list

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

Documentation for the `ssex_add_entry_to_list` script function, detailing its purpose and parameters. This function adds a database entry to a specified list.

```APIDOC
ssex_add_entry_to_list:
  Description: Adds a given entry to a list.
  Requires: To be in the scope of a database entry (use ssex_get_database_entry to get the reference).
  Parameters:
    identifier:
      Type: string
      Description: A database unique identifier of the list.
      Required: Yes
    index:
      Type: integer
      Description: The index for where to add the given list entry on the list.
      Optional: Yes
      Default: count - 1
```

--------------------------------

### Increment Stellaris Script Variable

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

The `ssex_increment` function provides a simple way to increase the value of a specified variable by one. This is a common utility for counters or progression tracking within Stellaris scripts.

```Stellaris Script
ssex_increment = {
	change_variable = {
		which = $variable$
		value = 1
	}
}
```

```APIDOC
ssex_increment:
  Parameters:
    variable: The name of the variable to increment.
```

--------------------------------

### Initialize Stellaris Script Extender Test Database

Source: https://github.com/oldent/stellaris-script-extender/blob/main/test/common/scripted_effects/AssertOther.txt

This script block initializes a global test database for the Stellaris Script Extender. It checks for the existence of a global database target; if not found, it creates a new database and saves its reference globally. This ensures a consistent environment for subsequent tests.

```Stellaris Script
init_assert = {
	if = {
		limit = { NOT = { exists = event_target:ssex_test_global_database } }
		ssex_clear_return_value = yes
		ssex_get_database = { identifier = ssex_test_database }
		if = {
			limit = { NOT = { exists = event_target:ssex_return_value } }
			ssex_create_database = { identifier = ssex_test_database }
		}
		event_target:ssex_return_value = { save_global_event_target_as = ssex_test_global_database }
	}
	ssex_clear_return_value = yes
}
```

--------------------------------

### Delete Stellaris Event Country by ID

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

This script finds and deletes an event country identified by its unique flag. It targets countries of type `ssex_country_event` that possess the specified identifier flag, then destroys them.

```Stellaris Script
ssex_delete_event_country = {
	random_country = {
		limit = {
			is_country_type = ssex_country_event
			has_country_flag = $identifier$
		}
		destroy_country = yes
	}
}
```

--------------------------------

### Copy Existing List to New Identifier

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

Copies an existing list to a new unique identifier. Allows specifying the number of items to copy (`count`), the starting index (`index`), and whether to overwrite an existing list (`overwrite`). This function is currently unimplemented.

```Stellaris Script
ssex_copy_list = {

}
```

--------------------------------

### API: ssex_get_list_entry Script Effect

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

Documentation for the `ssex_get_list_entry` script effect, detailing its purpose, parameters, and how to access the return value. This effect is used to retrieve an entry from a list based on various criteria.

```APIDOC
ssex_get_list_entry:
  Description: Retrieves a list entry from a Stellaris Script Extender list.
  Parameters:
    identifier: The database unique identifier of the list.
    index (optional): The index of the list item to retrieve.
    limiter (optional): A simple scripted_trigger accepting yes or no values (example: my_trigger = yes). The effect will input 'yes' for this trigger.
    first (optional): Exclusive with 'last'. If 'limiter' is filled, takes the first item found.
    last (optional): Exclusive with 'first'. If 'limiter' is filled, takes the last item found.
  Return Value:
    Access by scope: event_target:ssex_return_value
    Note: If neither 'first' nor 'last' are specified, the effect will select a random value.
```

--------------------------------

### Create and Add Entry to Stellaris Script Database List

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

This script effect, `ssex_create_list_entry`, is designed to create and add a new entry to a specified database or list within the Stellaris game environment. It handles both the initial creation of a list (if not present) and appending new items to an existing one. The script manages internal indices and utilizes leader flags for tracking list items and headers. It requires an `identifier` for the list and an optional `index` for the entry's position. The return value is accessible via `event_target:ssex_return_value`.

```Stellaris Script
ssex_create_list_entry = {
	[[index]
	set_variable = {
		which = ssex_list_append_index
		value = $index$
	}
	]
	if = {
		limit = { ssex_is_database = yes }
		save_global_event_target_as = ssex_hidden_scoped_list_database
	}
	else = {
		ssex_clear_return_value = yes
		ssex_get_database = { bound_to = this }
		if = {
			limit = { exists = event_target:ssex_return_value }
			event_target:ssex_return_value = { save_global_event_target_as = ssex_hidden_scoped_list_database }
			ssex_clear_return_value = yes
		}
	}
	if = {
		limit = { exists = event_target:ssex_hidden_scoped_list_database }
		event_target:ssex_hidden_scoped_list_database = {
			[[index]
			set_variable = {
				which = ssex_list_append_index
				value = prev
			}
			]
			random_owned_leader = {
				limit = {
					ssex_is_list_header = yes
					has_leader_flag = $identifier$
				}
				save_global_event_target_as = ssex_hidden_list_header_object
			}
			if = {
				limit = { exists = event_target:ssex_hidden_list_header_object }
				[[index]
				every_owned_leader = {
					limit = {
						ssex_is_list_item = yes
						has_leader_flag = ssex_list_item_of_@event_target:ssex_hidden_list_header_object
						check_variable = {
							which = ssex_list_index
							value = {
								scope = prev
								variable >= ssex_list_append_index 
							}
						}
					}
					change_variable = {
						which = ssex_list_index
						value = 1
					}
				}
				]
				create_leader = {
					name = ssex_database_entry_name
					class = governor
					species = event_target:ssex_database_entry_species
					immortal = yes
					effect = {
						set_leader_flag = ssex_item_in_list
						set_leader_flag = ssex_list_item_of_@event_target:ssex_hidden_list_header_object
						set_variable = {
							which = ssex_list_index
							value = { scope = event_target:ssex_hidden_list_header_object variable = ssex_list_item_count }
						}
						[[index]
						set_variable = {
							which = ssex_list_index
							value = { scope = prev variable = ssex_list_append_index }
						}
						]
						event_target:ssex_hidden_list_header_object = {
							change_variable = {
								which = ssex_list_item_count
								value = 1
							}
						}
						ssex_set_return_value = yes
					}
				}
				clear_global_event_target = ssex_hidden_list_header_object			
			}
			else = { log_error = "ssex_create_list_entry: No list with the given identifier exists" }
			[[index]clear_variable = ssex_list_append_index ]
		}
		clear_global_event_target = ssex_hidden_scoped_list_database
	}
	else = { log_error = "ssex_create_list_entry: Scope this is not a database and does not have an obviously accessable database" }
	[[index]clear_variable = ssex_list_append_index ]
}
```

--------------------------------

### Clear Stellaris Script Return Value

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

Clears a global event target `ssex_return_value`. This effect is often invoked automatically by other returning effects before they yield a result, making its explicit call frequently unnecessary in external scripts.

```Stellaris Script
ssex_clear_return_value = {
	if = {
		limit = { exists = event_target:ssex_return_value }
		clear_global_event_target = ssex_return_value
	}
}
```

--------------------------------

### API Documentation: Compare Two Strings for Equality

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_string_effects.txt

This section documents a function or event that compares two strings for equality within the Stellaris script environment. It outlines the required and optional parameters for identifying the strings and their respective databases, enabling robust string comparison operations.

```APIDOC
Compares two strings for equality

Parameters:
  identifier: A database unique identifier for the first string
  bound_to (optional): The scope that the primary string is stored to
  compare_identifier: A database unique identifier for the comparing string
  compare_database (optional): The database containing the comparing string
```

--------------------------------

### Initialize Stellaris Script Variable if Unset

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

The `ssex_ensure_variable_is_set` function checks if a given variable is already defined. If the variable is not set, it initializes it to a specified value or defaults to 0, preventing errors from undefined variables in subsequent script operations.

```Stellaris Script
ssex_ensure_variable_is_set = {
	if = {
		limit = { NOT = { is_variable_set = $variable$ } }
		set_variable = {
			which = $variable$
			value = $value|0$
		}
	}
}
```

```APIDOC
ssex_ensure_variable_is_set:
  Parameters:
    variable: The name of the variable to check for.
    value (Optional): The value the variable is set to; defaults to 0 if not specified.
```

--------------------------------

### Create/Clear Stellaris Global Event Target

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

This effect creates a new global event target. If a global event target with the specified `event_target_name` already exists, its value is cleared before the new value is saved. This ensures a fresh assignment for the target.

```Stellaris Script
ssex_save_global_event_target_as = {
	if = {
		limit = { exists = event_target:$event_target_name$ }
		clear_global_event_target = $event_target_name$
	}
	save_global_event_target_as = $event_target_name$
}
```

--------------------------------

### Reset List Enumerator Position

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

Resets a list enumerator to a specified index, defaulting to 0 (the start of the list). Requires the current scope to be a valid list enumerator. The `ssex_return_value` is set upon success. Logs an error if the scope is not an enumerator. Accepts an optional `index` parameter.

```Stellaris Script
ssex_reset_enumerator = {
	if = {
		limit = { ssex_is_list_enumerator = yes }
		set_variable = {
			which = ssex_current_index
			value = $index|0$
		}
		ssex_set_return_value = yes
	}
	else = { log_error = "ssex_reset_enumerator: The provided scope is not a validentifier list enumerator" }
}
```

--------------------------------

### Stellaris Script: Overwrite or Create Database

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_database_effects.txt

This Stellaris Script function overwrites an existing database or creates a new one if one does not already exist. It accepts 'identifier' (optional, unique identifier for global databases) and 'bound_to' (optional, the scope this database is bound to) parameters. If a database matching the parameters is found, it is first deleted, and then a new database is created. The new database reference is returned via `event_target:ssex_return_value`.

```Stellaris Script
ssex_overwrite_database = {
	[[identifier]set_global_flag = ssex_param_one_activated]
	[[bound_to]set_global_flag = ssex_param_two_activated]
	if = {
		limit = {
			NOR = {
				has_global_flag = ssex_param_one_activated
				has_global_flag = ssex_param_two_activated
			}
		}
		log_error = "ssex_get_or_create_database: Neither parameters identifier or bound_to are fulfilled, a database lacking both parameters cannot be managed or found once all scopes point away from it."
		break = yes
	}
	else = {
		remove_global_flag = ssex_param_one_activated
		remove_global_flag = ssex_param_two_activated
	}
	[[bound_to]
		if = {
			limit = { is_scope_set = $bound_to$ }
			save_global_event_target_as = ssex_hidden_database_owner_scope
		}
		elssex_if = {
			limit = { is_scope_set = event_target:$bound_to$ }
			save_global_event_target_as = ssex_hidden_database_owner_scope
		}
		else = {
			log_error = "ssex_get_or_create_database: Invalid scope reference passed by argument: bound_to"
			break = yes
		}
	]
	ssex_clear_return_value = yes
	ssex_get_database = {
		[[identifier]identifier = $identifier$]
		[[bound_to]bound_to = event_target:ssex_hidden_database_owner_scope]
	}
	if = {
		limit = { exists = event_target:ssex_return_value }
		event_target:ssex_return_value = { ssex_delete_database = { database = this } }
	}
	ssex_create_database = {
		[[identifier]identifier = $identifier$]
		[[bound_to]bound_to = event_target:ssex_hidden_database_owner_scope]
	}
}
```

--------------------------------

### Copy List to Another Database Object

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

Copies an existing list to a new unique identifier within another database object (scope). Allows specifying the number of items to copy (`count`), the starting index (`index`), and whether to overwrite an existing list (`overwrite`). This function is currently unimplemented.

```Stellaris Script
ssex_copy_list_to = {

}
```

--------------------------------

### Test Scope-Bound Database Creation, Retrieval, and Deletion

Source: https://github.com/oldent/stellaris-script-extender/blob/main/test/events/ssex_test_databases.txt

This Stellaris script defines a country event (`ssex_database_test.1`) to test database operations (creation, retrieval, and deletion) bound to the current scope (`this`). It verifies that a database can be correctly associated with a specific entity and its lifecycle managed within that context using assertion checks.

```Stellaris Script
country_event = {
	id = ssex_database_test.1
	is_triggered_only = yes
	hide_window = yes

	trigger = {}

	immediate = {
		init_assert = yes
		ssex_clear_return_value = yes
		ssex_get_database = { bound_to = this }
		assert_scope_not_exists = { SCOPE = event_target:ssex_return_value }
		if = {
			limit = { assert_passed = yes }
			ssex_create_database = { bound_to = this }
			assert_scope_exists = { SCOPE = event_target:ssex_return_value }
		}
		if = {
			limit = { assert_passed = yes }
			ssex_clear_return_value = yes
			ssex_get_database = { bound_to = this }
			assert_scope_exists = { SCOPE = event_target:ssex_return_value }
		}
		if = {
			limit = { assert_passed = yes }
			ssex_delete_database = { bound_to = this }
			ssex_get_database = { identifier = ssex_global_test }
			assert_scope_not_exists = { SCOPE = event_target:ssex_return_value }
		}
		if = {
			limit = { assert_passed = yes }
			log_error = "ssex_database_test.1 passed all tests"
		}
	}
}
```

--------------------------------

### Export Script List

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_list_effects.txt

Placeholder for a function to export every script list. This function is currently unimplemented.

```Stellaris Script
ssex_capture_script_list = {

}
```

--------------------------------

### Reset Stellaris Script Internal Comparison State

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

Resets the internal comparison state by removing the global flag `ssex_hidden_comparison_success`. This ensures a clean state for subsequent internal comparisons. This utility is strictly for internal use by the Stellaris Script Extender mod's logic.

```Stellaris Script
ssex_internal_reset_comparison = {
	remove_global_flag = ssex_hidden_comparison_success
}
```

--------------------------------

### Retrieve Stellaris Script Extender Database Object

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_database_effects.txt

This effect retrieves a database object. It requires at least one parameter: `bound_to` (an optional scope or event target representing the database's owner) or `identifier` (an optional unique flag on the database country). The found database is saved to `event_target:ssex_return_value`. An error is logged if neither required parameter is provided.

```Stellaris Script
ssex_get_database = {
	[[bound_to]
	set_global_flag = ssex_optional_parameter_set
	if = {
		limit = { is_scope_set = $bound_to$ }
		$bound_to$ = {
			if = {
				limit = {
					is_scope_type = country
					is_country_type = ssex_country_database
				}
				if = {
					limit = { exists = event_target:ssex_return_value }
					clear_global_event_target = ssex_return_value
				}
				save_global_event_target_as = ssex_return_value
				break = yes
			}
			else = { save_global_event_target_as = ssex_hidden_db_target }
		}
	}
	elssex_if = {
		limit = { is_scope_set = event_target:$bound_to$ }
		event_target:$bound_to$ = {
			if = {
				limit = {
					is_scope_type = country
					is_country_type = ssex_country_database
				}
				if = {
					limit = { exists = event_target:ssex_return_value }
					clear_global_event_target = ssex_return_value
				}
				save_global_event_target_as = ssex_return_value
				break = yes
			}
			else = { save_global_event_target_as = ssex_hidden_db_target }
		}
	}
	]
	[[identifier]set_global_flag = ssex_optional_parameter_set]
	if = {
		limit = { has_global_flag = ssex_optional_parameter_set }
		if = {
			limit = { exists = event_target:ssex_return_value }
			clear_global_event_target = ssex_return_value
		}
		random_country = {
			limit = {
				is_scope_type = country
				is_country_type = ssex_country_database
				OR = {
					[[bound_to]
					AND = {
						exists = event_target:ssex_hidden_db_target
						has_country_flag = ssex_bound_to_object_@event_target:ssex_hidden_db_target
					}
					]
					[[identifier]has_country_flag = $identifier$]
				}
				
			}
			if = {
				limit = { exists = event_target:ssex_return_value }
				clear_global_event_target = ssex_return_value
			}
			save_global_event_target_as = ssex_return_value
		}
		remove_global_flag = ssex_optional_parameter_set
	}
	else = { log_error = "ssex_get_database: A parameter was required but not given, to properly function  one of the parameters bound_to or identifier are required to be inputed." }
	if = {
		limit = { exists = event_target:ssex_hidden_db_target }
		clear_global_event_target = ssex_hidden_db_target
	}
}
```

--------------------------------

### Set Stellaris Script Internal Comparison to True

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

Sets the global flag `ssex_hidden_comparison_success`, indicating an internal comparison result is true. This utility is strictly for internal use by the Stellaris Script Extender mod's logic to manage conditional flow and should not be called externally.

```Stellaris Script
ssex_internal_set_comparison_true = {
	set_global_flag = ssex_hidden_comparison_success
}
```

--------------------------------

### Set Stellaris Script Internal Comparison to False

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

Removes the global flag `ssex_hidden_comparison_success`, effectively setting an internal comparison result to false. This utility is strictly for internal use by the Stellaris Script Extender mod's logic to manage conditional flow and should not be called externally.

```Stellaris Script
ssex_internal_set_comparison_false = {
	remove_global_flag = ssex_hidden_comparison_success
}
```

--------------------------------

### Set Stellaris Script Return Value

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_generic_effects.txt

Sets a global event target `ssex_return_value` to a new value. It first ensures any existing return value is cleared before saving the new one. This effect is intended for internal use within the Stellaris Script Extender mod and should not be directly used by external scripts.

```Stellaris Script
ssex_set_return_value = {
	if = {
		limit = { exists = event_target:ssex_return_value }
		clear_global_event_target = ssex_return_value
	}
	save_global_event_target_as = ssex_return_value
}
```

--------------------------------

### SSEx: Non-Comparable String API

Source: https://github.com/oldent/stellaris-script-extender/blob/main/source/common/scripted_effects/notai_ssex_string_effects.txt

This section describes the concept and usage of 'non-comparable strings' within the Stellaris Script Extender. These strings are optimized for dynamic content generation and are recommended for temporary use cases where string comparison is not required. It also details the `ssex_new_string` function for their creation.

```APIDOC
Non-Comparable Strings:
  Description: Easier to build strings and recommended for creating dynamically named objects. Can accept other objects as parameters for building a final string value. Recommended for creating a new string and destroying it upon build.

ssex_new_string:
  Description: Creates a new non-comparable string object and links it to the given scope.
  Parameters:
    identifier:
      Type: string
      Description: A unique identifier for the given string.
    text:
      Type: string (optional)
      Description: Creates the string with this text at the base. Text must be non-spaced.
    bound_to:
      Type: scope (optional)
      Description: Binds the string to the set object. Default value is 'this'.
```

--------------------------------

### Define Stellaris In-Game Keyboard Country Event

Source: https://github.com/oldent/stellaris-script-extender/blob/main/keyboard/events/notai_ssex_keyboard_main.txt

This script defines a `country_event` (ID `ssex_keyboard.0`) that acts as an in-game keyboard for player text input. It initializes necessary variables and flags (`ssex_keyboard_enabled`, `ssex_player_input`, `ssex_keyboard_current_index`) upon activation. Each `option` block within the event represents a character key press (e.g., 'a', 'b', 'c'), appending the corresponding character to a string (`ssex_player_input`) and handling capitalization based on a trigger. The event manages the input string and its metadata, allowing for dynamic text entry within the game environment.

```Stellaris Script
namespace = ssex_keyboard

country_event = {
	id = ssex_keyboard.0
	is_triggered_only = yes
	hide_window = no
	title = ssex_keyboard_title
	desc = ssex_keyboard_desc
	trigger = {
		is_ai = no
		ssex_is_keyboard_active_trigger = no
	}
	# Setting up necessary values and ensuring functionality for the keyboard
	immediate = {
		set_country_flag = ssex_keyboard_enabled
		ssex_get_or_create_database = { bound_to = this }
		event_target:ssex_return_value = { save_event_target_as = ssex_player_database }
		ssex_clear_return_value = yes
		ssex_new_comparable_string = {
			identifier = ssex_player_input
			overwrite = yes
		}
		event_target:ssex_return_value = { save_event_target_as = ssex_keyboard_desc_string }
		ssex_get_list_header = { identifier = ssex_player_input }
		event_target:ssex_return_value = { save_event_target_as = ssex_keyboard_input_metadata }
		event_target:ssex_player_database = {
			ssex_create_database_entry = {
				identifier = ssex_player_input_final
				overwrite = no
			}
			event_target:ssex_return_value = {
				set_name = ""
				save_event_target_as = ssex_keyboard_input
			}
		}
		set_variable = {
			which = ssex_keyboard_current_index
			value = 0
		}
	}
	### Keyboard options
	# Letters
	option = {
		name = ssex_key_a
		#custom_gui = ""
		is_dialog_only = yes
		responssex_text = ssex_keyboard_desc
		hidden_effect = {
			if = {
				limit = { ssex_keyboard_is_capitals_enabled_trigger = yes }
				ssex_append_char = {
					identifier = ssex_player_input
					char = ca
					index = ssex_keyboard_current_index
				}
			}
			else = {
				ssex_append_char = {
					identifier = ssex_player_input
					char = a
					index = ssex_keyboard_current_index
				}
			}
			ssex_keyboard_disable_shift = yes
			ssex_increment = { variable = ssex_keyboard_current_index }
			ssex_return_string = {
				identifier = ssex_player_input
				return_target = event_target:ssex_keyboard_input
			}
		}
	}
	option = {
		name = ssex_key_b
		#custom_gui = ""
		is_dialog_only = yes
		responssex_text = ssex_keyboard_desc
		hidden_effect = {
			if = {
				limit = { ssex_keyboard_is_capitals_enabled_trigger = yes }
				ssex_append_char = {
					identifier = ssex_player_input
					char = cb
					index = ssex_keyboard_current_index
				}
			}
			else = {
				ssex_append_char = {
					identifier = ssex_player_input
					char = b
					index = ssex_keyboard_current_index
				}
			}
			ssex_keyboard_disable_shift = yes
			ssex_increment = { variable = ssex_keyboard_current_index }
			ssex_return_string = {
				identifier = ssex_player_input
				return_target = event_target:ssex_keyboard_input
			}
		}
	}
	option = {
		name = ssex_key_c
		#custom_gui = ""
		is_dialog_only = yes
		responssex_text = ssex_keyboard_desc
		hidden_effect = {
			if = {
				limit = { ssex_keyboard_is_capitals_enabled_trigger = yes }
				ssex_append_char = {
					identifier = ssex_player_input
					char = cc
					index = ssex_keyboard_current_index
				}
			}
			else = {
				ssex_append_char = {
					identifier = ssex_player_input
					char = c
					index = ssex_keyboard_current_index
				}
			}
			ssex_keyboard_disable_shift = yes
			ssex_increment = { variable = ssex_keyboard_current_index }
			ssex_return_string = {
				identifier = ssex_player_input
				return_target = event_target:ssex_keyboard_input
			}
		}
	}
	option = {
		name = ssex_key_d
		#custom_gui = ""
		is_dialog_only = yes
		responssex_text = ssex_keyboard_desc
		hidden_effect = {
			if = {
				limit = { ssex_keyboard_is_capitals_enabled_trigger = yes }
				ssex_append_char = {
					identifier = ssex_player_input
					char = cd
					index = ssex_keyboard_current_index
				}
			}
			else = {
				ssex_append_char = {
					identifier = ssex_player_input
					char = d
					index = ssex_keyboard_current_index
				}
			}
			ssex_keyboard_disable_shift = yes
			ssex_increment = { variable = ssex_keyboard_current_index }
			ssex_return_string = {
				identifier = ssex_player_input
				return_target = event_target:ssex_keyboard_input
			}
		}
	}
	option = {
		name = ssex_key_e
		#custom_gui = ""
		is_dialog_only = yes
		responssex_text = ssex_keyboard_desc
		hidden_effect = {
			if = {
				limit = { ssex_keyboard_is_capitals_enabled_trigger = yes }
				ssex_append_char = {
					identifier = ssex_player_input
					char = ce
					index = ssex_keyboard_current_index
				}
			}
			else = {
				ssex_append_char = {
					identifier = ssex_player_input
					char = e
					index = ssex_keyboard_current_index
				}
			}
			ssex_keyboard_disable_shift = yes
			ssex_increment = { variable = ssex_keyboard_current_index }
			ssex_return_string = {
				identifier = ssex_player_input
				return_target = event_target:ssex_keyboard_input
			}
		}
	}
	option = {
		name = ssex_key_f
		#custom_gui = ""
		is_dialog_only = yes
		responssex_text = ssex_keyboard_desc
		hidden_effect = {
			if = {
				limit = { ssex_keyboard_is_capitals_enabled_trigger = yes }
				ssex_append_char = {
					identifier = ssex_player_input
```