Sahrani Electrical Grids (ACCEPTED)

[Loyalguard]

Sahrani Electrical Grids
by Loyalguard

UPDATED:  08 January 2008 - Version 1.05 has been released.  Download package (including demo mission) in this post has been updated.

The Sahrani Electrical Grids (SEG) is a package of scripts that simulate electrical power grids on Sahrani by turning off street lamps when the substation that they are "connected to" by the simulation receives more than 50% damage. It also includes an option for mission makers to enable players to manually turn power off and on.

Demo Video at YouTube: Sahrani Electrical Grids Demo
NOTE: You may need headphones in order to hear the substation hum in the video.

-Release version and Date: v1.05 - 08 Jan 2008
-100% scripting
-No Addons required
-Version 1.08 or later required (compatibility with previous versions not tested)
-Fully SP, MP and JIP compatible
-Demo Mission included
-No known bugs, errors, or issues

Developmental Change Log

Version 1.05 (Additional Minor Setup Fix)
-Adjusted how JIP updates are conducted for newly joining players so that the SEG JIP update will not prevent other JIP code required for the mission from running.

Version 1.01 (Minor Setup Fix)
-Adjusted how custom sounds for SEG are included in the mission maker's Description.ext file to avoid conflict with other potential custom sounds.  See "Mission Maker Instructions" Step 3 in SEG_README.txt.

v1.0 (First Final Release)

v0.9.3 (Fifth Beta Release)
-Substations emit a humming noise when energized via an additional script (only runs locally while player is near substation to reduce CPU stress)
-Simplified Description.ext implementation instructions by defining sounds via a .hpp #include instead of editing of class CfgSounds in the Description.ext file.

v0.9.2 (Fourth Beta Release)
-Added mission maker option to have a buzzer alarm sound at a substation when power is manually turned off/on.
-Simplified and removed unnecessary code for off/on actions.

v0.9.1 (Third Beta Release)
-Added three additional scripts (now four in total) to provide added functionality and placed them all in a sub-folder named "SEG" for ease of locating.
-Added easy to use customization options for mission makers to determine which substation grids are created and whether or not to enable players to power off/on substations without having to damage them.
-Adjusted damage requirement routine for Corazol West and East to better conform with the 50% damage threshold model.
-Converted a smaller number of large grid zones to a larger number of small grid zones to reduce CPU stress and network traffic.
-Full MP/JIP Compatibility.
-Removed the ability to repair/rebuild substations due to ArmA engine limitations with JIP.

v0.8 (Second Beta Release)
-When power is restored, street lamps are now switched to "auto" instead of "on" so they are only on at night
-Damage requirements for the substation at Corazol West have been adjusted to more closely follow the 50% damage  requirement
-Demo Mission is now multiplayer with three player positions for better MP/JIP compatibility testing (must be made a .pbo and loaded to a dedicated server for MP use)
 
First Beta Release was v0.7

Demo Mission Only Changes
-Added hint at beginning of mission to orient and instruct new players.
-Added grid zone map to demo mission to better show grid coverage.
-Added playable positions at each substation (in addition to the three already at Dolores) to test each substation grid as desired.
-Added AH-6 to initial spawn point (Dolores) to allow for transportation to other parts of the island to test individual grids.

Switching off street lamps as a result of "power" or "electrical system" events is not a new concept, but to my knowledge this is the first island-wide simulation of electrical power grids in ArmA.  This script package simulates seven different electrical power grids on Sahrani by turning off street lamps when the substation that they are "connected to" by the simulation receives more than 50% damage or is manually controlled by a player. The scripts are not complicated, but it took a lot of work to make sure the code syntax was correct (lots of strings within strings and coordinate issues).  As such, I spent several weeks making sure it looked clean before posting.  Here are the specific features, requirements and notes:

Specific Testing Objectives

I have tested this in SP, MP LAN, and on a dedicated server and in all my tests the scripts work as they should (all players, even newly joined, see lights on or off as appropriate).  However, I want to make sure it is completely compatible with all game modes before final release.

I am also interested in validation of the features that I have included in the script as well as ease of use regarding changing of custom options to suit mission maker desires.  I would also like input on additional features that mission makers might like to make use of in the simulation if feasible.

Lastly, as a new scripter, I am always looking for ways of writing more efficient code.  If you find any ways for me to improve the structure or content of my scripts please do let me know!
 
Possible Applications for this Resource

Coop Missions: There are some existing missions by various authors that include "cutting power" to substation as objectives. This script provides a framework for easily creating these types of objectives.

Team vs. Team Missions: In addition to the possibility for TvT objectives, the script also provides for "blackout scenarios" for night ops or persistent missions.

Realistic Game Immersion: For all gametypes; Coop, TvT, Rolepaying; this script makes ArmA more realistic and increases immersion by giving the power substations and the street lights across the island actual functionality.

For more information on how to incorporate SEG into objectives in your mission see "Special Notes and Considerations" in the readme file.
 
How SEG Works

SEG is a package of four scripts located in a sub folder that is placed inside the mission folder.

The primary script, SEG_Init.sqf, creates a game logic and multiple triggers for each of the substations on the island that work in concert to simulate an electrical power grid as follows:

A game logic is placed within the perimeter of each substation and through the nearestObject command it finds one of the two possible type of transformer class objects in ArmA ("Land_trafostanica_velka") which are present at all substations.

One trigger monitors the current damage level of every large transformer within the 50m range of the game logic. When damage exceeds 50% it activates and broadcasts publicly they change in power status to the server and all game clients. Mission makers also have the option to enable the creation of two additional triggers that give nearby players an action menu option to turn power off and on (one trigger for each) without having to damage the substation. If used, they also broadcast publicly the change in power status.

When a change in power status is broadcasted (either by damage or manual action), another trigger that controls the power to the street lamps is activated and it in turn executes the second script: SEG_Events.sqf.  Instead of a separate script for each trigger event, they are combined in a single .sqf and and only the pertinent code is executed each time using a switch-do statement bock.  When executed, every street lamp within a specific radius of the trigger using the nearObjects command is located and turned off by the switchLight command. Because some substations "supply" power to more than one zone, additional commands may be included.
All the possible manual off/on actions for the substations are created by the addAction command in the appropriate trigger and execute the corresponding code in the third script: SEG_Actions.sqf. Instead of a separate script for each AddAction, they are combined in a single .sqf and and only the pertinent code is executed each time using a switch-do statement bock.

The fourth script in the folder is SEG_JIPUpdate.sqf. This script is executed by SEG_Init.sqf after all pertinent substations (and their corresponding global variables) have been created. The script broadcasts publicly the current condition of each variable so that all players in-game see the same lights on or off as appropriate.

The fifth script, SEG_SubHum.sqf, is activated by a trigger at each substation that makes the substation emit an electrical humming noise while the player is close enough to hear it.

The scripts are fully commented for ease of review. Since the code creating the variables, logic, and triggers for each substation is so similar, only the code for the first substation (Paraiso) is commented (but all subsequent substations use near identical code except for positions, logic, trigger, and variable names).
 
The Readme contains full details on how the script pack works.

These are just a few of the various scenarios that can be developed using this script as a framework. There are many more possibilities depending on how creative and/or complicated the mission designer wants to get.

I gathered snippets and found relevant advice for making of this script from Mandoble and bardosy; Balschoiw, pauld, and lebon506th at the BIS Forums; and Strag and Shiner at the TacticalGamer.com Forums.  Full acknowledgments and relevant threads are listed in the readme.
 

OFPEC DOWNLOAD

[Loyalguard]

v0.8 Update

v0.8 has been released (first post link updated) to make some minor adjustments:

Change log from v0.7 to v0.8
===========================

-When power is restored, street lamps are now switched to "auto" instead of "on" so they are only on at night
-Damage requirements for the substation at Corazol West have been adjusted to more closely follow the 50% damage requirement
-Demo Mission is now multiplayer with three player positions for better MP/JIP compatability testing (must be made a .pbo and loaded to a dedicated server for MP use)

I have some much better insight into MP/JIP compatibility now.  I made the demo mission fully MP with three player positions to better define local/global issues.  Here is the current state of MIP/JIP/Locality issues:

1) If one player destroys a substation all other players also connected will see the substation destroyed and the lights turn off.

2) The examples I have given showing how to "shutdown", "power on", and "restore" do not work for all MP clients since those triggers are local with no public variable associations.  I am working on this issue.

3) A player that joins after a substation is destroyed will not see the substation (player will either see ruins if the server is running the latest beta dedicated server version or nothing) but street lamps will still be on for the JIP player.  This is a major issue for JIP enabled and persistent missions and I will work to resolve it (most likely with public variables or nearestObject command parameters).  This issue does confuse me though.  Even though the JIP player's trigger is local, when he connects the script should be run on his client and the trigger should recognize the substation is damaged/destroyed and switch off the corresponding lights.  My only theory as to why it does not work is perhaps once a object is destroyed completely it no longer "exists" at all and therefore does not register with the trigger since I am searching for object classes and not actual object IDs with the nearestObject command in the trigger.  This might require some major adjustments.  Any other theories?

Thanks to everyone who has tested this so far and please feel free to provide any additional insight or feedback.

[LCD]

seems to work fine... even tho i wud apricieate if inside da example mision u wud mark (use markers) da difrent grids... also mebe make it more user friendly and give an action (addactopn command) 2 shut it down (or at least give instructions on how 2 make dat easily...) as right now i cant b bothered 2 try 2 do somin like dat by myself (Still lil drunk from yesterdayz )

LCD OUT

[Loyalguard]

seems to work fine... even tho i wud apricieate if inside da example mision u wud mark (use markers) da difrent grids... also mebe make it more user friendly and give an action (addactopn command) 2 shut it down (or at least give instructions on how 2 make dat easily...) as right now i cant b bothered 2 try 2 do somin like dat by myself (Still lil drunk from yesterdayz )

LCD OUT

Thanks for the feedback LCD.  I will definitely add the grid zone markers to the demo mission.  Also like you suggest, I am strongly leaning towards building in the ability to ability to power down, power on, and repair/restore the substations directly in the script and mission makers can enable them by changing a variable from 0 to 1 if they want to include those features in their mission.  Thanks again!

UPDATE -  27 Nov 2007:

I am making good progress on implementing full MP/JIP compatability, it is just a slow process since the entire simulation model has to be re-worked.  Nevertheless, I have Dolores fully functional tested in the editor, LAN, and dedicated server.  I hope to have version 0.9 ready within a few days.  I have also included the option for mission makers to power off/on the substations without blowing them up if they want without having to create their own triggers, addActions, or other methods.

I have encountered a peculiar bug though that may change the ability to restore/repair/rebuild a damaged/destroyed workstation.  I can blow one up so it is completey destroyed, rebuild it so you can see the undamaged model of the substation and the lights automatically turn back on, disconnect, reconnect and see that the power is still on but there is no substation model!  I tried re-rebuilding it but it has no affect because it is technically still there but you can't see and can walk through where the model is unimpaired.  You also can't blow it up again because there is no model to destroy.  It's like the object is there but there is no model.  I am going ot put it on the bugtracker when it comes back up.  If this is a persistent issuem then I may have to replace the abiliy to re-build the substation completely with putting a generator in its place with less capacity.

[Loyalguard]

v0.9.1 Update

v0.9.1 has been released (first post link updated) making some major improvements to give full MP/JIP compatability.

After an almost complete re-write of the script to give full MP/JIP compatability using public variables and the addition of three other scripts to improve organization and functionality, v0.9.1 (Beta) has been released.  The change log below (as well as in the first post) covers all the changes.  The readme in the upload link fully documents all the internal workings of the scripts.  I feel pretty strongly that this will be a release candidate unless some major problems are encountered but I have spent several hours testing on a dedicated server so I feel pretty confident.  Thanks again for testing!

Change Log

 v0.9.1 (Third Beta Release)
-------------------
-Added three additional scripts (now four in total) to provide added functionality and placed them all in a sub-folder named "SEG" for ease of locating.
-Added easy to use customization options for mission makers to determine which substation grids are created and whether or not to enable players to power off/on substations without having to damage them.
-Adjusted damage requirement routine for Corazol West and East to better conform with the 50% damage threshold model.
-Converted a smaller number of large grid zones to a larger number of small grid zones to reduce CPU stress and network traffic.
-Full MP/JIP Compatibility.
-Removed the ability to repair/rebuild substations due to ArmA engine limitations with JIP.

Demo Mission Only Changes
------------------------------------------
-Added grid zone map to demo mission to better show grid coverage.
-Added playable positions at each substation (in addition to the three already at Dolores) to test each substation grid as desired.
-Added AH-6 to initial spawn point (Dolores) to allow for transportation to other parts of the island to test individual grids.

[LeeHunt]

hey Loyalguard,

Very thorough and well thought out resource  .

1) Can you add a hint and directions at the beginning of the demo?  And tell the player exactly where to stand near the Power substation?  Most people download a resource and jump into the demo mission without reading the documentation. Though your readme was well written and thorough, I did just that- jumped in to see what was there and was kind of clueless for a few moments. Those few moments might make the difference between someone using your resource in a mission or not.   

2) maybe some kind of Star Wars-esque "powering down" sound for the substation?  Or alarm or something? What do you think?

Anyway, i already thought of a way to include this in my next mission so thansk Loyalguard, very cool and well done 

[Loyalguard]

Lee-

Thanks for the feedback. 

1) I will add a hint with directions at the beginning of the demo.  Excellent idea and should be easy to implement.

2) I like the idea of "powering down" effects.  I definitely think some kind of klaxon ("ah-ooh-gah") might be a good idea.  Perhaps even a flashing yellow light attached to the substation using a #lightpoint.  I have also thought of a custom dialog for the powering down/up action instead of just the action menu as well.  I will definitely look into the sound though.  I will probably make it a mission maker option in the SEG_Init.sqf in case some mission makers want to be able to have absolute stealth.

Thanks for the ideas!

[Loyalguard]

v0.9.2 Update

v0.9.2 has been released (first post link updated) which implements suggestions from LeeHunt.

Change Log

v0.9.2 (Fourth Beta Release)
-Added mission maker option to have a buzzer alarm sound at a substation when power is manually turned off/on.
-Simplified and removed unnecessary code for off/on actions.

Demo Mission Change Only
-Added hint at beginning of mission to orient and instruct new players.

In lieu of the buzzer and also as Lee suggested, I am looking at some possible power on/down sounds in conjunction with an ambient hum at the power stations as well.  Thanks again for the suggestions Lee!

[LeeHunt]

--------------------------------------------------------------------------------
cool Loyalguard. I'll give it a try again this weekend. I was thinking of using this in a mission where Sahrani has been evacuated due to zombies, nuclear accident, bad guys, etc etc. thanks for making it


UPDATED:

Ok looks good Loyalguard. I like the klaxon sound, and the hint makes it more clear for the player what to do.  Let's wait a bit and see if there are any other suggestions, but looks good 

[Loyalguard]

v0.9.3 Update

Thanks again to everyone for their feedback.  This release really should be the final beta before 1.0.  The only changes are that I added a pulsating electrical hum to the substations while the power is on for a more realistic environment (I wanted a consistent hum but despite hours of editing the sound and adjusting the sleep delay, even when looped via scripting there is a small pause between say commands) and made it easier to implement SEG into the missions by makers using #include and a .hpp in the Description.ext instead of the mission maker having to manually insert the sounds in class CfgSounds.  Here is the changelog.  First post updated with new download link as well.

Change Log

v0.9.3 (Fifth Beta Release)
-Substations emit a humming noise when energized via an additional script (only runs locally while player is near substation to reduce CPU stress)
-Simplified Description.ext implementation instructions by defining sounds via a .hpp #include instead of editing of class CfgSounds in the Description.ext file.

[LeeHunt]

looks good, just two minor things-- can you put the player start back in Dolores?  And any chance the trigger radius for the addaction ON and OFF can be widened?  Sometimes it takes a bit of walking to find the switch?  otherwise 

[Loyalguard]

Oops!  Sorry about the initial player spawn!  I had moved it for testing in the editor and forgot to move it back before uploading.  I have updated the first post with the corrected version.  Still v 0.9.3, just a new file with the same number.

Regarding the on/off addAction radius...The addAction is attached to the transformer object by the appropriate trigger based on the status of the power on/off public variable, not by area detection, so it appears at a certain distance from a point in the transformer model, not at a radius from the trigger so I am not sure what else I can to extend it.  From my testing it seems that the position in the transformer object model to where the addAction is set is not the center of the model as we see it in-game.  It seems like it more in a corner (using the Dolores example, as you approach it, the far right corner I think).  So, yes, it does take some walking around to find a good spot spot to bring up the option.

I can look at one alternative, there is a game logic at the "center" of each substation.  I can look into attaching the addAction to the game logic instead of the transformer object itself.  Maybe that will make the distance to the addAction more uniform from center and easier to access.  It should only be 14 or so lines of code to change so I'll take a look and see how well it works.  Thanks Lee!

Edited for Update: Apparently you cannot attach an addAction to a game logic.  I just spent about an hour trying different ways with no luck.  I think I remember this problem with invisible H pads as well.  Has anyone else been able to attach an addAction to a logic?  In lieu of that solution, does anyone else has a recommendation for adding the action to the "substation"?  It's not too bad the way it currently is...it kinds makes it a challenge like trying to find "the switch" amongst all the other components.  But, I do want to find the best implementation for mission makers and players.  Thanks!

[johnnyboy]

so it appears at a certain distance from a point in the transformer model, not at a radius from the trigger

I've had problems with model positions not being truly center of object as well. 

Maybe you could place a game logic in a relative position to the Transformer object using modelToWorld?

You can experiment placing a visible Flag pole object using ModelToWorld in relation to the Transformer, until you find the perfect relative position. Just an idea...

I like this feature you are working on.  Nice additional resource for mission makers.  Thanks.

[Loyalguard]

Version 1.0 released.  First post updated and status changed to Ready.

After several more hours of reviewing code, exploring other features, and play testing I would like to request Sahrani Electrical Grids v1.0 be considered for submission to the Editors Depot.

Thanks to everyone again for their advice, suggestions, help, and testing!

[LeeHunt]

Great Loyalguard! i'll take the final look and we'll have it up soon