############################################################
Gas Can - Fuel Spill Weapon
------------------------------------------------------------
CLEO Script for GTA San Andreas
Author: AlvarynGTA | Version: 1.0
############################################################

A functional Gas Can gameplay mod powered by a modular Oil System framework.

This mod introduces a usable fuel can weapon capable of creating dynamic oil puddles that ignite, propagate fire logically, and interact with the environment.

The included Oil System is a reusable modular backend with configurable puddle growth, ignition, propagation, and cleanup behavior while remaining compatible with GTA SA native fire systems.

A major technical inspiration was Oil Leaking by Junior_Djjr, particularly the rendered oil droplet concept, which helped motivate the development of a more complete reusable oil framework.


Requirements:
-------------
* GTA: San Andreas v1.0
* CLEO 4
* CLEO+
* ModLoader
* fastman92 Limit Adjuster
* Open Limit Adjuster (recommended)


Installation:
-------------
1. Copy the `Gas Can + Oil System` folder into your `modloader` directory.

2. Configure:
* `Gas Can\cleo\petrolcan.ini`
* `Oil System\cleo\OilProperties.ini`

3. Use the included files in:
`Weapon Config`

4. Set:
`Gas Can\cleo\petrolcan.ini`

WeaponTypeID =
to match your chosen weapon ID.

5. Follow the fastman92 setup below.

6. Enjoy.


Usage:
------
1. Obtain the Gas Can pickup from included locations or add your own weapon source.
   (`PetrolCanPickups.cs` provides optional distributed pickups.)

2. Equip the weapon and hold fire to pour fuel.

3. Oil puddles can ignite from:
* nearby fire
* supported bullet impacts
* burning neighboring puddles

4. Use strategically against vehicles, enemies, or environmental hazards.


Features:
---------
[Gas Can]
* Functional Gas Can weapon
* Dedicated carry / pouring visual behavior
* Custom Gas Can asset (Blender weapon model, custom texture, custom HUD icon)
* Optional pouring sound support
* Fuel droplet particle effects
* Ammo consumption while pouring
* Infinite ammo compatibility with:
  - Infinite ammo cheat
  - GTA SA 100% completion unlock
* Safe savegame handling while carrying the weapon
* Safe GTA SA local 2-player compatibility
* Optional PetrolCanPickups.cs pickup module
* Distributed pickups across San Andreas gas stations + Doherty garage
* Save-safe pickup restoration system

[Oil System]
* Stable modular oil puddle runtime framework
* Dynamic oil puddle spawning
* Puddle growth / merge logic
* Nearby fire ignition detection
* Supported bullet impact ignition
* Logical chain fire propagation
* Gas pump object explosion reactions
* Configurable oil/fire properties
* Automatic puddle lifecycle cleanup
* Distance-based cleanup using current `CWorld::PlayerInFocus`
* Registry validation cleanup
* Reusable public runtime framework for other compatible scripts


Technical Notes / Limitations:
-----------------------------
* Oil puddles are simple individual rendered spill instances
* Puddles are static once created and exist only on mapped world surfaces
* Oil does not conform to or render onto moving collision surfaces such as vehicles
* Only standalone gas pump objects are detected
* Some Las Venturas gas stations use static IPL/map-integrated models rather than destroyable standalone objects, so they will not react
* Bullet ignition detects supported projectile impacts only
* Sniper weapon impacts are not currently detected
* Fire ownership remains attributed to the original oil creator
* Oil puddles are rendered every frame
* Performance scales with active puddle count
* GTA SA uses a native fire pool with a base limit of approximately 60 simultaneous active fires; if saturated, new ignition or propagation may temporarily fail


Oil System Framework:
--------------------
The Oil System is designed as a reusable modular oil runtime framework.

Compatible external scripts can generate oil through the public runtime request buffer instead of implementing separate spill systems.

Basic integration:
1. Oil System initializes a public request buffer
2. Buffer pointer is written to:
   `Oil System\cleo\OilProperties.ini`
3. External scripts read that pointer
4. Oil requests are sent through the shared buffer
5. Oil System handles puddle lifecycle centrally


fastman92 Limit Adjuster Setup:
-------------------------------
Required in `fastman92limitAdjuster.ini`:

Enable weapon type loader = 1

Increase +1:
Weapon type loader, number of type IDs

To prevent crashes when using added model IDs increase:
Count of killable model IDs

Weapon Config includes ready-to-use setup files.

Choose:
* a free weapon ID
* a free model ID

In fastman92 `gtasa_weapon_config.dat` add:

[ID]	PETROLCAN	-1	1	0	100	27	89	130	1.0

Important:
* Replace `[ID]` with your chosen free weapon ID
* Parent type MUST remain EMPTY
* Anim group MUST be `flame`

In:
`Weapon Config\Weapon Lines\weapon.ide`

replace:
`[modelID]`

In:
`Weapon Config\Weapon Lines\weapon_loader_lines.txt`

replace:
`[modelID]`

`weapon_loader_lines.txt` already includes:
* IDE loading
* weapon.dat loading

Set:
`Gas Can\cleo\petrolcan.ini`

WeaponTypeID =
to match your chosen weapon ID.

Optional:
`Weapon Config\HUD Icons`
includes alternative weapon icons.

Recommended:
Use Open Limit Adjuster together with fastman92 Limit Adjuster.


Internal Naming Note:
---------------------
Internal asset and script naming retains legacy compatibility naming (`petrolcan*`).


Future Notes:
-------------
Future expansion may further evolve the Oil System into a more flexible modular backend.

Potential long-term improvements include:
* Per-script configurable oil profiles
* OilProperties.ini acting as default fallback values only
* Multiple fuel variants using the same backend (Red / Yellow / Blue Gas Can)
* Improved rendered puddle backend
* Surface tracking support for moving entities such as vehicles
* Larger-scale Oil System architectural refactors or plugin-based evolution