SR2 Lua Files List

This topic describes what Lua files exist in the Saints Row 2 data files, and the purpose of each Lua file.

All Lua scripts (except multiplayer maps) are included in Gentlemen of the Row v1.9.2, inside the "modified" and "original_patch" folders under "optional_mod_stuff" folder.

=== About the Lua "Contexts" ===
Saints Row 2 have two concurrently-running Lua virtual machines and each has access to certain kind of builtin functions provided by the game. I'd call these virtual machines as "Contexts".

One context is "Gameplay" which controls all story missions and stronghold missions of the game. There is also a script "sr2_city.lua" that is always running during solo and co-op. The scripts in Gameplay context have access to functions that affects the gameplay directly, such as spawning_pedestrians(boolean) which allows or disallows walking peds spawning, and cash_add(amount, player) which gives the player specified amount of cash.

The other context is "UI" which controls much of the game's menus and HUD. The scripts in UI context have access to functions with vint_* prefix (i.e. vint_insert_values_in_string) but what each script can actually do is very specific to each script.
Many of the game's menus are dependent on a system called "data responder" which the script requests certain kind of data to the game (by calling "vint_dataresponder_request") and the game responds to it. However, the game silently ignores such request from a "wrong" place (you can't query the player's clothing from the Pause Menu, for example).

Certain functions are shared between contexts. These functions include coop_is_active() which returns true in co-op mode, thread_yield() which temporary pauses the current thread and let other threads run (I think the game uses Cooperative/Non-preemptive multitasking) and rand_int(min, max) which produces a random number between min and max (both min and max are inclusive).
There is also one special Lua script "original_patch\system_lib.lua" which is loaded by the both contexts. This script contains a function delay(duration) that pauses the execution of a thread for the specified number of seconds. This file also sets up the error handler that would be triggered when an undeclared variable got referenced in a Lua script. You can technically modify this script to define global variables, but the actual contents of the variables are not shared between Gameplay and UI contexts.

Although many things are controlled by Lua, there are many more things in the game that are NOT Lua controlled. These include logic of all activities, cutscenes, the diversion stars on the HUD, and weapon switching via mouse wheel and number keys. Options for some of these are exposed via xtbl and cts files, but otherwise mostly hardcoded.

=== Gameplay Context ===
==== Globals ====

modified\mission_globals.lua: Global variables and functions for missions. Also handles pre-mission phonecalls that happens before tss03 Down Payment and some of Brotherhood missions.
modified\sr2_city.lua: "Master Lua Script for Saints Row 2", always loaded and running in campaign mode. Sandbox+ mod modifies this file to provide all functionality.
original_patch\ug_lib.lua: Common functions and constants used by Gameplay context (e.g. LOCAL_PLAYER, MISSION_START_CHECKPOINT, mission_start_fade_out(), etc)
original_patch\stronghold_globals.lua: Intended for global variables and functions for Strongholds, but it has no global variables defined, and all functions are empty.

==== Missions ====
modified\tss01.lua: Jailbreak
modified\tss02.lua: Appointed Defender
modified\tss03.lua: Down Payment
modified\tss04.lua: Three Kings
modified\sh_tss_caverns.lua: Stilwater Caverns

original_patch\bh01.lua: First Impressions
modified\bh02.lua: Reunion Tour
original_patch\bh03.lua: Waste Not Want Not
modified\bh04.lua: Red Asphalt
original_patch\bh05.lua: Bank Error in Your Favor
modified\bh06.lua: Thank You and Goodnight!
modified\bh07.lua: Retribution
modified\bh08.lua: Jail Bait
modified\bh09.lua: The Enemy of my Enemy
modified\bh10.lua: The Siege
modified\bh11.lua: Showdown
modified\sh_bh_apartments.lua: Sommerset Apartments
modified\sh_bh_chinatown.lua: Imperial Square Pagodas
modified\sh_bh_docks.lua: Poseidon Alley Docks
modified\sh_bh_airport.lua: Wardill Airport Hangars

modified\rn01.lua: Saint's Seven
modified\rn02.lua: Laundry Day
modified\rn03.lua: Road Rage
modified\rn04.lua: Bleeding Out
modified\rn05.lua: Orange Threat Level
modified\rn06.lua: Kanto Connection
modified\rn07.lua: Visiting Hours
modified\rn08.lua: Room Service
modified\rn09.lua: Rest In Peace
modified\rn10.lua: Good D
modified\rn11.lua: One Man's Junk...
modified\sh_rn_stripclub.lua: Suburbs Strip Club
modified\sh_rn_sciencemuseum.lua: Humbolt Park Science Museum
modified\sh_rn_museum_pier.lua: Amberbrook Museum Pier
modified\sh_rn_rec_center.lua: New Hennequet Rec Center

original_patch\ss01.lua: Got Dust, Will Travel
original_patch\ss02.lua: File in the Cake
original_patch\ss03.lua: Airborne Assault
original_patch\ss04.lua: Veteran Child
original_patch\ss05.lua: Burning Down the House
original_patch\ss06.lua: Bad Trip
modified\ss07.lua: Bonding Experience
modified\ss08.lua: Riot Control
original_patch\ss09.lua: Eternal Sunshine
modified\ss10.lua: Assault on Precinct 31
original_patch\ss11.lua: The Shopping Maul
modified\sh_ss_trailerpark.lua: Elysian Fields Trailer Park
modified\sh_ss_crackhouse.lua: Bavogian Plaza Drug Labs
modified\sh_ss_student_union.lua: Stilwater University Student Union
modified\sh_ss_fishingdock.lua: Sunnyvale Gardens Fishing Dock

modified\ep01.lua: Picking a Fight
modified\ep02.lua: Pyramid Scheme
modified\ep03.lua: Salting the Earth... Again
modified\ep04.lua: ... and a Better Life
modified\sh_tss_ugmall.lua: Rounds Square Shopping Center

modified\em01.lua: Revelation
modified\dlc04.lua: Traffic Control
modified\dlc05.lua: Corporate Meltdown

==== Districts ====
The game has many "district" scripts that are loaded and executed by sr2_city.lua. These scripts ended up mostly unused in the released game.
Each district has three functions: "init", "main", and "warp".
The warp function warps the player to the chosen district for debugging purposes, and Sandbox+ mod makes use of the warp location ("navpoint") originally used by this function. (The warp function itself, on the other hand, is not used by Sandbox+.)
The init and main functions are empty in all districts. The intension of these functions was probably to execute custom district-specific codes when the player enters the hood.

original_patch\airport.lua: Airport
original_patch\apartments.lua: Apartments
original_patch\arena.lua: Arena
original_patch\barrio.lua: Barrio
original_patch\chinatown.lua: Chinatown
original_patch\docks.lua: Docks & Warehouses
original_patch\downtown.lua: Downtown
original_patch\factories.lua: Factories
original_patch\highend.lua: High End Retail
original_patch\hotels.lua: Hotels & Marina
original_patch\museum.lua: Museum
original_patch\nuke.lua: Nuclear Power Plant
original_patch\prison.lua: Stilwater Prison
original_patch\projects.lua: Projects
original_patch\redlight.lua: Red Light
original_patch\saintsrow.lua: Saint's Row
original_patch\subexp.lua: Suburbs Expansion
original_patch\suburbs.lua: Suburbs
original_patch\trailerpark.lua: Trailer Park
original_patch\truckyard.lua: Truck Yard
original_patch\ultor_base.lua: The Pyramid. Contains a commented out code that spawns a Pimp Cane, but otherwise identical to other district scripts.
original_patch\underground.lua: Underground (Old Stilwater, Rounds Square Shopping Center, and Stilwater Caverns)
original_patch\university.lua: Stilwater University

==== Multiplayer Maps ====
These files are NOT included in GotR mod and must be extracted from "chunks4.vpp_pc" in the game's directory.
The extraction tool is available in "optional_mod_stuff\tools\Gibbed.SaintsRow2.ExtractPackage.exe" in GotR.

chunks4\multi_hunters.lua: Strong Arm Police spawning and AI manager
chunks4\sr2_mp_lobbytut.lua: Strong Arm Tutorial Lobby
chunks4\sr2_mp_sa_ba2.lua: Script for a multiplayer map, init police stuff

==== Unused ====
original_patch\ai_test.lua: AI test mission; contains a code that make a NPC walk between two places
original_patch\coop_test.lua: Likely a test mission for co-op. Sets a checkpoint when Satchel Charge is picked up and when a vehicle is entered. The script contains many other unused functions that tests various things such as adding cash or show timer on HUD.
original_patch\em02.lua: Empty mission. The only thing it does is set the mission author to "Your Name Here".
original_patch\fr_checkAI.lua: These fr_check*.lua are "Framerate Check" mission scripts that were probably used for benchmarking. These scripts contain codes that moves camera automatically and spawns effects such as smoke and fire.
original_patch\tss03_demo.lua: An early version of tss03 Down Payment. It does not contain proper checkpoint support and there was a boss fight against a character named "Bumaga".
original_patch\usability1.lua: "SR2 usability testing script". Contains some codes that make you race against the clock using a boat.
original_patch\usability2.lua: "SR2 usability testing script 2". Spawns a plane, teleports the player into it, and do nothing afterwards.

=== UI Context ===
==== Globals ====

original_patch\vint_lib.lua: Common functions and global variables used by UI context
original_patch\menu_base.lua: Menu code, handles many things such as controls and menu graphics

==== Stores and Triggers ====
modified\cdl01.lua: Vehicle Dealer
modified\clothing_store.lua: Clothing Stores and Wardrobe
modified\pcr01.lua: Plastic Surgeon
modified\vehicle_cust.lua: Vehicle Customization UI at Rim Jobs/Semi Broken
original_patch\activity_level.lua: Activity Level Selector that shows up when you replay an activity
original_patch\building_purchase.lua: Store/Crib Purchase Confirmation Dialog and the Purchased screen
original_patch\crib_cust.lua: Crib Customization
original_patch\garage.lua: Garage
original_patch\gang_cust.lua: Gang Customization
original_patch\gmb_blackjack.lua: Blackjack
original_patch\gmb_poker.lua: Menu code for Poker
original_patch\liquor_store.lua: Food/Liquor Stores
original_patch\mission_replay.lua: Crib Newspaper Clipboard
original_patch\music_store.lua: "Scratch That" Music Store
original_patch\television.lua: Crib Television
original_patch\weapon_store.lua: Weapon Stores and Weapons Cache

==== Menus ====
modified\city_load.lua: Loading Screen (when a save file is being loaded)
modified\cellphone.lua: Cellphone
modified\pause_menu.lua: Pause Menu
original_patch\completion.lua: Mission Complete/Failed Screens
original_patch\credits.lua: Credits
original_patch\demo_derby.lua: Demolition Derby Menu
original_patch\dialog_box.lua: Message Dialog Box, also handles Zombie Uprising Pause Screen
original_patch\main_menu.lua: Main Menu (Note, the Pause Menu is loaded at the same time and the Main Menu makes full use of it)
original_patch\menu_style_dialog.lua: "Style Rank Increased" dialog
original_patch\mp_completion.lua: Multiplayer Match End Screen
original_patch\mp_leaderboards.lua: Online Leaderboards
original_patch\mp_lobby_players.lua: Player List in Multiplayer Lobby Pause Menu
original_patch\mp_match_load.lua: Multiplayer Map Loading Screen
original_patch\mp_player_info_popup.lua: Multiplayer Player Info Popup
original_patch\mp_scoreboard.lua: Scoreboard in Multiplayer Gameplay Pause Menu
original_patch\mp_server_browser.lua: Multiplayer and Co-op Server Browser
original_patch\multi_pause_menu.lua: Multiplayer Lobby Pause Menu
original_patch\pause_map.lua: Map Screen
original_patch\tutorial.lua: Tutorial Popup Boxes
original_patch\tutorial_subtitles.lua: Strong Arm Tutorial Subtitle
original_patch\hud_coop_div.lua: Co-op Diversion Results Screen

==== HUD ====
modified\hud.lua: Main HUD code, handles player's health bar, sprint bar, respect bar, homie indicators, cash, notoriety, and radial menu. Also handles weapon switching by Q key.
original_patch\mp_hud.lua: Multiplayer Gameplay HUD
original_patch\mp_hud_lobby.lua: Multiplayer Lobby HUD
original_patch\hud_btnmash.lua: Button Mash Bar in Fight Club, Ambulance EMT(, and Zombie Uprising?)
original_patch\hud_demo_derby.lua: HUD for Demolition Derby. Handles health bars for players and enemies.
original_patch\hud_gsi.lua: HUD codes for "GSI" (Global Status Indicator?); handles mission, activity, and diversion status display
original_patch\hud_healthbars.lua: Health bars for targets in Septic Avenger, enemies in Fight Club, and the partner in Co-op. Also handles money indicator in Insurance Fraud and Rank Number in Race. Note, this script does NOT handle the enemy health bars in Demolition Derby; they are handled by "hud_demo_derby.lua".
original_patch\hud_mayhem.lua: Mayhem/Septic Avenger/Trail Brazing bonus effects
original_patch\hud_mp_hud.lua: Multiplayer Snatch HUD?
original_patch\hud_msg.lua: On-screen messages on HUD
original_patch\hud_multi_prototype.lua: Multiplayer specific HUD stuff for Tagging and Activity Scores
original_patch\hud_race_start.lua: The "3..2..1..GO!" start countdown in Racing, Trail Brazing, Demolition Derby, and Fight Club
original_patch\hud_reticules.lua: Reticules
original_patch\hud_touch_combo.lua: Ho-ing HUD
original_patch\hud_zombie.lua: Zombie Uprising HUD

==== Cutscene Stuff ====
original_patch\cte_news6.lua: News6 TV ticker in tss02 "Appointed Defender" intro cutscene
original_patch\cte_sniper_rifle.lua: Gat's sniper rifle view in ep04 "... and a Better Life" intro cutscene

==== Unknown and Unused ====
original_patch\cutscene_test.lua: Unknown, no real codes
original_patch\cutscene_tv.lua: Something related to TVs in cutscenes? Maybe completely unused?
original_patch\mm_wireless.lua: Advertisement screen for SR2 mobile game. Unused in the PC version.
original_patch\ss_grid.lua: Contains some codes that shows or hides "thirds" and "golden_ratio" but I'm unsure what this Lua was supposed to do.
original_patch\menu_gambling_poker.lua: Unused? Does not seem to be used by Poker minigame