Poser readScript Documentation - Copyright © 2002 Robert E. Whisenant

Last updated: Monday, April 7, 2003 0:22 MST (GMT -0700)

readWhat? (readScript)

Author : Rob Whisenant (aka "rbtwhiz")

 NOTE :  This document is geared toward Poser users that have some knowledge of how the internals of Poser files are constructed. If you are new to Poser, I wouldn't recommend tackling this tutorial just yet. A fellow Poser user (Kevin Rose) had written  this  as an explanation of P3 cr2 files quite a while ago, and it may bring you to a point where this document will make more sense. You may also find  this  tutorial at DAZ Arcana (by Ted St. John) useful in bringing you up to speed.

What:

readScript is an undocumented command within Poser's internal code that allows a content creator to link calls to external files from within one of Poser's native [ascii] formats. SO... Big deal, right? Not quite. See, this command opens the door to a couple different things. It negates duplication and drive space consumption by curbing the need to have multiple versions of any base figure for the sake of a "character" by storing reusable data in a centralized location by which you can call into action when needed, vice without choice when each copy of a figure is loaded in the paradigm we've all been accustomed to up until this point. It also allows original developers to assert and protect their copyright on proprietary intellectual property, as well as allowing downstream content developers a chance to keep themselves out of trouble while still profiting from their work; a win-win situation. Not to mention that it provides a vehicle for those downstream developers to distribute well thought out, complete, products while keeping user interaction relatively simple.

When, Where, Why:

readScript began its life as a command that Poser used to load the initial figure upon launch when the factory default settings where used. The command exists in its original form, in the file "\Runtime\figures\default.figure". The contents of that file, in a standard Poser 4 Pro Pack install with Service Release 3 applied, looks like this:

----------------snip----------------
{

version
     {
     number 3.0
     }
     
     //--------------------------------------------------------
     // These are commented out lines. You can switch these and/or modify
     // the name to change the default figure
     //--------------------------------------------------------
     // readScript GetStringRes(1032,24)
     // readScript ":Runtime:libraries:character:People:Casual Man.cr2"
     // readScript ":Runtime:libraries:character:Poser 4 Lo:Casual Man P4 Lo.cr2"
     //readScript ":Runtime:libraries:character:Poser 2 Lo:Casual Man P2 Lo.cr2"
     readScript ":Runtime:libraries:character:Poser 2 Lo:Default Guy.cr2"


}
----------------snip----------------

The "//" lines are, as you can clearly see above, commented out lines. As such, when the file is read, Poser sees the "//" and bypasses anything that exists on those particular lines; whether it be actual code or descriptive text, it doesn't matter. Above, there are several "readScript" lines that point to different character files within Poser's runtime directory. And as the text indicates, you can link a different file to change the default figure.

"readScript:" is more useful than just, THAT.
In trying to find a better solution to housing memory hungry morph targets in DAZ's  Victoria 3 , I decided to put on the ol' thinking cap and "try a few things." I figured... if "readScript" can tell poser to load a figure from a specific location on launch, certainly I can make it point to a file of my choosing and have it load that instead. So, I changed the path to load a prop... instead of a figure. And load, it did. "Hmmm..." I thought, well if that worked then perhaps I could place it in a minimized [pz2] pose file (brackets, version, etc.), make it call another pose... and apply that poses as if I selected IT [the pose itself] from the library. Tests proved fruitful. ;)

Usefulness:

To expand on what I mentioned up a couple paragraphs... There are a number of content developers in the market that utilize DAZ's proprietary morphs, at mixed values in pose files, to result in a desired look ("character"). Being that 3rd generation Millennium figures don't have all of their morphs loaded by default, like the 2nd generation versions do, something is needed to ensure the morphs exist in the base figure before a pose is applied to manipulate the figure's look; otherwise the dials are spun, but if the morph is not loaded the affect is not apparent and the whole point of the pose is lost. readScript provides a way to accomplish this task, without much (if any) required from the user, and very little required from the developer... except perhaps, cognizant thought. With a little creativity, a content developer that utilizes the readScript command can do much more than first seems useful...

How:

By now you're likely saying something along the lines of "Okay, enough hype, show me how already!", right? Well, much of it depends on what you aim to do, but I'll show you a simple version of a scenario that is likely to be very common...

----------------snip----------------
{

version
     {
     // To keep from some users getting error messages, this should be number [3.0, 4.0 or 4.01]
     number 4.01
     }
     // A pose from the library; it injects the deltas and unhides the channel via readScript of its own
     // the calls reference core Victoria 3 files
     readScript ":Runtime:Libraries:Pose:!V3 Head INJ:HdAfrican3.pz2"
     // A pose from the library; it applies a MAT pose for the natural map in V3's hi-res maps
     readScript ":Runtime:Libraries:Pose:!MAT V3 MapsHi:! V3NaturalHi.pz2"
     // A pose from the library; it applies a MAT pose for light brown eyes in V3's hires maps
     readScript ":Runtime:Libraries:Pose:!MAT V3 MapsHi:Eyes BrownHi.pz2"
     // A pose from the library; it applies a MAT pose for a dark complexion in V3's hires map
     readScript ":Runtime:Libraries:Pose:!MAT V3 MapsHi:!Tone 7.pz2"
     
// The group with the morph to turn on
actor head:1
     {
     channels
          {
          // The morph to turn on
          targetGeom HdAfrican3
               {
               keys
                    {
                    // Turn it on
                    k 0 1
                    }
               }
          }
     }
}
----------------snip----------------

Above is a snippet of code that will inject the delta [morph] information for the "HdAfrican3" morph ( Victoria 3.0 Head Morph Pak ), load the natural map, change the eye color to brown and set the skin tone to a dark color ( Victoria 3.0 Universal Texture Maps (High Res) ). In the example, you'll see several comment lines. They have been placed within the code to help you understand what is going on and/or what the intent is. Notice that the morph is called before the value is set? It is good practice to ensure that you first make the morph available before you change the value.

To create the pz2, you'll need an ascii text editor (I recommend  EditPadPro  for PC users and  BBEdit  for Mac users). But remember, if you start from an existing pz2 to get the formatting correct... SAVE A COPY AND WORK FROM IT, NOT THE ORIGINAL.

Mwwuuhahahahaa... If I wear this disguise, nobody will recognize me!
Um, not true Mr. Evil Mastermind. Because Poser's native files are all based on the same [ascii] format, and they [the ones mentioned] are applied in a similar manner... you can easily save a [pz2] pose file into the face library with the fc2 extension and it'll work fine. You could also save it into the camera or light (although from the light library it'll turn all the lights off) libraries if you really wanted to, you'd just need to use the correct extension for it to show up within Poser, under that specific library. The questions is... will it confuse your users?

But, but, but... I saved a face to my library and now its not working!
One thing you must understand is that, like the majority of other advancements in Poser-land, this is a hack. Poser wasn't meant to do these things... at least not like this. With any figure that uses technology as advanced as  Victoria 3 , you must be ready for change (to whatever degree it exists). Due to the fact that she uses  delta injection , the actual morph deltas must exist in the figure, for the affected channels, before you'll see the affect of a pose. Huh? Keep reading...

That face file you saved isn't useless. As a matter of fact, it is still very valuable. See, by manipulating it in a text editor manually or using a utility to do the work automatically, you can use that file to create a pose/face file that injects the morphs it sets... before it sets them. In the next paragraph I'll get into using a cr2 to create "Character Poses."

If you are doing the work manually and you jump down past the first seven steps... to the part that says " You should now weed out any channels that have a value of "0" ," you can continue from there and you will have made excellent use of your saved face file.

Pop quiz, hot-shot! You want to create full blown "character" for V3. What do you do? WHAT DO YOU DO?
Well, that largely depends on how well you understand readScript and to what degree you want to involve yourself in the internals of Poser files. For a seasoned vet, the internals of Poser files are a walk in the park, for a user that is either new to hacking or has never hacked the files Poser reads... it can be daunting.

The Automatic Way.
Seeing the need for something that would automate much of this, I wrote a tool.  INJection Pose Builder  , is the utility I originally wrote to simplify the process and speed up production time for DAZ's production department. After some internal discussion, we decided tweak it (which included adding Macintosh support) and release to the public. And though it'll seem biased coming from me, being that I wrote it, it makes creating the poses simple... even... dare I say, convenient. Basically, what the utility does is parses an input cr2/pz2/fc2, using a set of options you select, and creates the INJ/REM pose for you. As time has permited, I've continued development on the tool... so updates that provide increased funtionality will be posted as that functionality warrants it.

The Manual Way.
Automatic utility or not, some people like to know the dirty details of it. I know this because I'm one of those people! That said, I'll explain the manual way, anyway. If you're on a PC its quite easy (but time consuming), you'll need Poser 4, a free utility by the name of  MAT Pose Edit  and a decent text editor ( EditPadPro  or the FREE version  EditPadLite ; EPP is worth it's weight in gold to anyone who spends much time in the internals of Poser files!). If you're on a Mac you don't have the luxury that MPE provides and you'll likely need to do much of the part that involves MPE manually.

  • Use Poser to load  Victoria 3  , inject the appropriate morphs and spin the dials to set the values that make up your character.
     NOTE :  All of the body morphs in Victoria 3 can be controlled from the BODY group, in addition to their local location. For the sake simplicity, it is easiest to make your adjustments from there.
  • Apply the applicable REM pose to remove all injected deltas from the figure
     NOTE : The deltas only occupy valuable memory that could be better used somewhere else. If enough deltas are loaded it may likely cause MPE to stop responding.
  • Save the figure back to your library under your character's name.
  • Open the cr2 in your text editor and remove the actors that you did not adjust from both the head section (between the figureResFile referrences) and the joint section (actor name....).
     NOTE : This is also done to prevent MPE from ceasing to respond.
  • Save the cr2 again, under the same name (it is only being used to build the pose file).
  • Locate and load the cr2 [character] you saved, in MPE (when asked if you want to load morph and pose data, click yes. It'll take a second to finish loading.)
     NOTE :  If you do not intend to include material settings, apply maps, set channel values and call morphs from a single file (or you plan to call MAT settings as external files via readScript)... you may want to go to the "General Options" tab and place a checkmark in the "No Material data" checkbox.
  • Go to the "Morphs and Pose dials" tab, select all of the body parts you did NOT adjust in Poser and delete them (not needed if you already did this above - MPE memory/hang issue).
  • With the remaining groups selected, click the "All Pose channels" button in the "Delete channels" dialog.
  • Save As... a pose file in your pose library.
  • Locate and load the pz2 (or whatever you saved it as) into your text editor.
  • You should/could now weed out any channels that have a value of "0".
     NOTE :  It's actually up to you whether or not you need to. It depends on your intended method of application (zero morphs and apply the pose OR applying the pose without care to what other morphs are currently set ).
     NOTE :  How you do that is up to you, but if you are using EditPadPro's search and replace function (regular expression), it is very simple. Just copy/paste an entire channel (unaffected; 0 key values) with an extra CR/LF (shift + Return) into the "Search text" field, substitute the internal name of the channel with ".*$" (between quotes, for : any character to end of line) and check the "Regular expression" box from the side options. Leave the "Replace text" field empty and check the "Start from Beginning" option. Replace All... and viola, slim and trim.
  • Once you've weeded out the zeroed channels (if you chose to do so), you'll need to add the calls to inject the morph targets and unhide the channels for the user. Mimicking the formatting shown  above , for each channel that exists (no duplicates), insert a call to the appropriate files.
     NOTE :  Each of the INJ/REM files included in a default install of Victoria 3 (and her morph paks) makes two of it's own calls. One calls the morph injection pose from within the "!DAZ" folder in the libraries hierarchy under runtime and the other calls the channel visibility pose. The easiest thing to do would be to insert calls to the file that does both (inject/unhide) in the pose folder, but some people may have moved the default location of the V3 Pose files, which may be cause for redundancy in the file you are creating (by calling each file independently: inject, unhide, inject, unhide, inject, unhide).
  • Save and test in Poser.

A pinch of this... a little of that... a dash of that and there we have it.
If you want to stay legal while building derivative morphs (ones that you didn't build completely on your own), much of how to build the pose is identical to what is described in the steps above. The difference being that in order to not violate the owner's copyright of the morphs you used to get to your result... you'd need to make sure your work, and the work you build on top of is both separate and additive. What I mean is, you'd need to create a  delta injection  pose that only contains the changes you made from scratch as its own morph. Then by adding all the values you used to reach the look of the "character", you'd end up with said character.

If part of how you are building the morph for your "character" is within Poser, there are a few things you must do to ensure you are not infringing the right of the other creator.

  • Spin up the dials to the values you desire, taking care to record the specific values you applied.
  • Add your original custom modifications; be they additional morphs or the use of Poser's deformers (magnets).
     NOTE :  see the  Delta Injection tutorial   for other things to consider.
  • Spawn a new morph within Poser.
  • Using the recorded information from above, inverse out the values (positive becomes negative, negative becomes positive) used on the morphs you did not create yourself.
  • Spawn another morph; this will be only your changes.
  • Save a cr2 to your figure library.
  • Using the saved cr2, create a morph injection pose for your morph. (  Delta Injection tutorial   )
  • Create a channel visibility pose to hide/unhide appropriate channels. (  ChanVis tutorial   )
  • Follow the steps  above .

 NOTE :  It is good practice to also provide a removal (REM) pose along with the injection (INJ) one. The easiest way to create one is by starting from an injection pose and just changing all of the key values back to "0". Then change the calls to external files, to point to poses that remove delta information and hide the unused channel. Inspect Victoria 3 files for an example of this.

Crosstalk:

What affect does crosstalk have?
It is claimed to be fixed in the current most version of Poser, but crosstalk has plagued the Poser community for years. If you haven't upgraded, like the many who haven't, crosstalk is still an issue. So how do we combat it? Well, much the same way we did before... with a minor change. Until recently, all morphs for a figure were usually included in the cr2... with the new approach that  Victoria 3  presents, they are not. So, we need to prepare the files in order to utilize the  previous process  , for EACH figure you aim to include in the final scene:

  • With a new, blank scene, load the default cr2
  • Inject all the morphs required for the "character"
  • Save the cr2 to your library
  • Once all "characters" are prepared, use the  same steps as before 

If you are already familiar with how to use the "Millennium Null", you can download it here . To refresh your memory on how to use it,  go here .

Multiplicity:

But... but... I want more!
Is there a limit to the number of readScript commands I can stack before Poser will choke? I'd imagine there is, but I haven't found it.  Victoria 3  includes a few files that cascade hundreds of them through multiple files and they all behave as expected.

Order! Order! Order in this court!
Does order make a difference? Yes. The order you place the readScript commands is the order Poser will execute the content of the linked file. To illustrate this, think for a moment about the example above. Had I put the call to the brown eye MAT before the call to the natural maps MAT in the example, the eyes would render the color of the natural maps, which is blue... not brown.

Cascade... No, not the dishwashing detergent!
readScript in one file can call another file which also uses readScript to call yet another file (which may do the same thing, until some point that you actually get to a file with some substance). But a word of advice would be, to be careful and keep things as concise as possible. Not only will others appreciate it, but you will too... in the event that you need to troubleshoot why something isn't functioning correctly.

Nurse, can you administer this patient's vaccinations?
You may be wondering if readScript can be injected into a file within Poser... To the best of my knowledge, that answer is no. My research shows, if a readScript line is present in a cr2, though the linked code may execute and the values may be applied, Poser will not save the resultant cr2 with readScript calls in tact ( I say "may" because although I have accomplished loading maps into poser via readScript in a cr2, I've yet to see a pose apply, maps actually be applied, material settings be applied, inject morphs... etc). This suggests that any attempt to inject the code will incur the same result.

Huh? Think about it... You are already applying a pose with readScript calls in it. If you were to save a cr2 with the readScript equipped pose applied and inspect it, do you find any calls? No. Hence the conclusion, it can not be injected.

Save As...

With your pz2 saved, test it in Poser... and keep an open mind. Your first attempt may not go as you had planned. My suggestion would be to relax, it is extremely simple... don't overanalyze it ;).

Copyright © 2002 Robert E. Whisenant. All Rights Reserved.  www.rbtwhiz.com