Expanding Sapien To Its Full Potential.

Intended for those who already understand the basics of Sapien.

The Command Console:
Many functions/globals are left out in the well-known keyword lists for scripting and these can be very valuable in taking advantage of Sapien, especially for campaign map designers. Experienced developers have probably seen this type of thing before, but it's understandable if not, considering that it isn't exactly common knowledge.

Here is an alphabetized list of all acceptable functions executable via console and script. Sapien spat this out, but it also mixed in a ton of garbled phrases and jargon. I've been working on cleaning this up for the past few days and I finally managed to cut it out down to only script functions (if you spot any leftovers, just let me know). Here it is online: http://www.cereal-ki...mand%20list.txt

Now I'll talk briefly about some of the many things that you can do with script globals not listed in the popular "Script Bible," "Scripting Keywords List," or, "hs_doc." There are about 2-3 times as many compared to script functions (they do not include descriptions as of yet, although I may go through it and add those in the future), and many of them are only functional in Sapien. Here are some that I tested recently and found interesting and/or useful:

(rasterizer_fog_plane [boolean]) - This turns fog planes on or off, most notably in water. So, for instance, if you were dealing with something underwater and couldn't see worth anything, just set that to "true" and it'll be clear as day. This works in-game as well.

(rasterizer_mode [short]) - This cycles through a few modes of the rasterizer (default is 0). They all have slight lighting changes, but mode 1 is like a ghost mode and makes geometry glow while being slightly transparent. This does not work in-game.

(debug_objects [boolean]) - Setting this to "true" enables an assortment of other debug_objects functions/globals to be used (the list is alphabetized, so you can easily find them underneath). By default when you use this, debug_objects_collision_geometry and debug_objects_bounding_spheres are "true" but you can disable them if you like. One that I really find useful is debug_objects_names which prints the name of an object next to it in a purple font. This is useful to me especially in massive army-on-army cutscenes. This does not work in-game.

(run_game_scripts [boolean]) - This one is trickier to use, but it has by far the most valuable results if you're making a solo-player map. First, make sure that any scripts in the map that change the camera position are "dormant" not "startup" (it will crash if the camera_set command is used). I'd actually suggest all scripts being "dormant" for testing purposes but it's not necessary. Then you can type (wake ) and it is executed in Sapien. Now that you have that ready to go, you can simply test a cutscene in Sapien, or even some gameplay that doesn't require the player to advance. This cuts out the process of repeatedly making a tiny change then recompiling, saving you a considerably large amount of time and monotony.

(debug_scripting [boolean]) - This is a useful global to use alongside run_game_scripts. Set it to "true" right before, and it renders real-time debugging of your scripts to help you if you're running into any issues.

Expect this post to be updated with more functions/globals in the near future - we've hardly begun to scratch the surface

Child Scenarios:
Have you ever been working on a map with so much in it that Sapien begins to lag (frequently and intensely)? Well with child scenarios, that is an easy issue to fix. Start out by creating a new scenario (can be done in Guerilla with file > new) and add the same bsp(s) that your map uses. The sky doesn't matter, the final map will use the sky(skies) from your main scenario. Now open your main scenario in Guerilla, and scroll until you see "child scenarios". Click "add" and find the one you made. Save it and you can exit Guerilla. In Sapien, open the new scenario you just made. You can continue object placement in here, as if it were your main scenario. When you use tool to compile the map, just compile the main scenario like normal; it will automatically add the objects in the child scenario(s) to the main one, since it was listed as a child to the main. Scripts in the main scenario can even reference scripts in the child scenario.

Other Helpful Tidbits:

Precise Object Placement:
I've recently been talking to people about the benefits of Sapien over Sparkedit (these people are experienced in both, mind you) and the most common defense of Sparkedit was its "precision of object placement" in that you are able to translate objects along axes with the arrow keys. I found this odd, considering Sapien does exactly that. This brought to my attention that many people did not know Sapien had this capability: once an object is selected in the game view, up/down = y-axis, left/right = x-axis, hold shift and up/down = z-axis. It translates the object exactly 0.02 units along the axis per individual key press, holding down will smoothly slide it. Holding ctrl allows you to use the arrow keys to rotate the object.

Using Different Skies Within the Same Map:
So have you ever wanted to change skies in a map mid-game, but not known how? Well here's the secret, and it's not script-related! First, let's start with adding the skies you want to use for different bsps. In Guerilla, open your scenario file and click "add" on the skies section. Choose the one you want, and then open the dropdown box where it lists the skies. The first one should be 0 and the second one should be 1. Likewise, the next one you add will be 2 and so on. Save it and then open another bsp used in your map that you want to have the second sky you added (if you want to have the same bsp just change skies, then make a copy of that bsp and add it to your scenario). Bsps take a while to open sometimes, so be patient. When it finally does, scroll down until you see this:
In that box, you type in the number of the sky you want the bsp to use from the scenario (starting with 0). So, if you want this bsp to use the second sky from your scenario, type "1" in the box. Also, for it to work, you have to apply it to every cluster. Right above the number, open the dropdown box and go to the next cluster. Apply it to this one as well, and so on. It is a pain in the ass, but it's the only way.

Approved. I edited some of your post to use "functions" and "globals" and they're two different things. The hs_doc script function only spits out documentation for other script functions, which is why you don't see any of these globals in it.

Ah, I called them functions out of habit I suppose, because I got in the mindset of "anything you don't type 'set' in front of is a function." Also I figured that the script function lists included mainly only commands that were used in-game.

No, you misunderstand its purpose. Its for organization purposes really. You can have a child scenario containing the scenery for the map, or another with just cutscene flags/etc. It cuts down on the clutter you might otherwise have in a busy map.

You still have to recompile the bsp in order for it to update in sapien. As long as you haven't deleted/renamed your original scenario file, all objects/settings will still be there. The bsp is referenced in the scenario tag, its not tied directly to it.