Creating Web Hamr Content

From Animation Master Wiki
Jump to navigation Jump to search

This needs to be “wiki ified”
Here is the origional link

 WebHAMR content creation:
 
 WebHAMR content is created with the Hash Animation:Master (A:M) program.
 If you plan on saving A:M content in binary form or plan on using the HAMR.hxt plugin for creating content interactivity, you should be using A:M V13.0i or later.
 
 If you just want content to be viewable in WebHAMR without using binary format
 files and without special interactivity, you can use any version of A:M to produce the content.
 
 Refer to the following link for more information about A:M.
 
 http://www.hash.com
 
 1) WebHAMR works best if A:M is used to save the models, actions, textures etc. as a PRJ project file rather than as individual MDL, ACT etc. files.  Also, it is best to select the "Project, Embed All" option forcing all A:M MDL, ACT etc. files for the project to be encapsulated in the single PRJ file.  Some files such as images and sounds will still be separate files even if the project is saved in embedded format.
 
 It is also best to use the A:M "Consolidate" option to save the PRJ file and all of its required files (such as images etc) into a single directory.  Just pay attention where this directory is so that later you can reload the PRJ file and export it as binary if desired and so that you can zip up all of the needed files.
 
 2) If you wish to make your project data safe from reverse engineering, you should right click on the Project Work Space (PWS) in A:M and then select "Export" and then select "project as HA:MR binary (.PRJB)".  Projects exported in binary format can be loaded by WebHAMR (and HAMRViewer)  for display but not by A:M and thus cannot be edited or changed once distributed.  Don't forget to save a copy of the project for yourself in PRJ text format since you will not be able to load the PRJB binary file back into A:M.
 
 If you "Consolidated" your PRJ file as described in the above section, you will need to reload it in A:M from the consolidation directory.  Once that is done, export your PRJB file as above into this same consolidation directory.
 
 3) Prior to distributing your project on the web, you need to zip up the project and all supporting files into a compressed zip file. How you do this is up to you. A:M doesn't currently have a zipping ability.  By zipping the files up you only have to worry about having one file to download later from the web and also the total amount of data to download will be reduced via the compression. The name of the zip file is up to you.  WebHAMR when run will download this file to a temporary directory, unzip it and look for loadable content.  I.E., it will attempt to load the single .PRJ or single .PRJB file contained in the zip.  If it does not find either of these, it looks for a MDL file and if it finds one, loads it and then looks for an ACT file and if it finds one, it loads that also.
 
 Remember when you zip up your consolidated directory that you select the highest level consolidation directory  for inclusion in the zip file.  If you fail to include the entire consolidation directory and subdirectories, you may not have some files available when the file is later unzipped by WebHAMR.
 
 4) Transfer your project zip file to your web server directory that you wish to make available over the net to users.
 
 5) WebHAMR is distributed with two sample HTML files to help you get started in making your zipped project available for download and display by WebHAMR. The two files are Template1.html and Template2.html .  The first is a bare bones file whose only job is to start WebHAMR and download the zipped file to WebHAMR.  The second is a more advanced file that shows how to used JavaScript to do some things with the project once WebHAMR has loaded it. For most uses, the first, simple HTML template is sufficient for allowing display of the project as well as user interactions with the project models.
 
 Your HTML file should be transferred to your web server directory where you want users to be able to access it.
 
 Following is the content of the Template1.html file for your reference.  To use it, just substitute the web address for your zipped project in place of the example address in the CWebHAMRCtrl LoadModel( line.
 
 <HTML>
 <HEAD>
 
 <SCRIPT LANGUAGE="JavaScript">
 </SCRIPT>
 
 <SCRIPT LANGUAGE="JavaScript" FOR="window" EVENT="onload()">
 <!--
     CWebHAMRCtrl.LoadModel("http://www.hash.com/hamr/KeeKatHAMR.zip")
 -->
 </SCRIPT>
 
 <SCRIPT LANGUAGE="JavaScript" FOR="CWebHAMRCtrl" EVENT="OnProjectLoaded(name)">
 <!--
   //CWebHAMRCtrl.DoStartPlay()
 -->
 </SCRIPT>
 
 </HEAD>
 
 <TITLE>New Page</TITLE>
 <BODY>
     <OBJECT ID="CWebHAMRCtrl"
      CLASSID="CLSID:B33B2E29-17FF-44D6-8F6E-8D5ACE47D0A6"
      width="100%"
      height="100%">
 
      <table border="0" height="100%" width="100%" bgcolor="#ffffff">
        <tr>
          <td>
              <p align="center">
              <font face="Verdana" size="4" color="#000000"> <br>
              If you are unable to view the graphical content of this page,<br>
              it is probable that the WebHAMR viewer is not installed.<br>
              By clicking <a href="http://www.hash.com/hamr/Download.htm">
              this link</a> you will be taken to the WebHAMR install page.</font>
          </td>
        </tr>
      </table>
 
     </OBJECT>
 </BODY>
 </HTML>
 
  For any A:M project file that is distributed via the web to WebHAMR, the user will be able to interact with it in the following manner by selecting the mode buttons in the toolbar at the bottom of the screen.
 
 1) Turn- The default mode.  Click the left mouse button on a project model (an object in the display scene) and while holding it down, move the mouse to cause the scene to turn around the selected object as the center of rotation.
 
 2) Move-  Click the left mouse button anywhere in the scene and while holding it down, move the mouse to cause the scene to move around.
 
 3) Zoom-  Click the left mouse button anywhere in the scene and while holding it down, move the mouse to cause the scene to zoom in or out.
 
 After any of these mode movements, the user can return to the original "camera view" by pressing the '1' key on the keyboard, either above the letter keys or in the numeric keypad.
 
 Other number keys can be used to change the view just like in A:M as listed:
 - '1' or 'C' camera view
 - '2' front view
 - '4' left view
 - '5' top view
 - '6' right view
 - '7' birds eye view
 - '8' back view
 - '0' bottom view
 
 In addition to the above interactivity functionalities, the artist can use A:M to embed further information in the project file that enables more sophisticated user interaction.  Once so embedded, these interactive capabilities are available to the WebHAMR user with no additional information being required in the HTML file.  I.E., although WebHAMR has JavaScripting capabilities, you do not have to provide scripting in order for the user to interact with the project models via the embedded information.
 
 Embedding interactivity information in a project is done via the HAMR.hxt A:M plugin.  The HAMR.hxt plugin allows the artist to add interactivity information to the project.  If you have the HAMR.hxt plugin installed for A:M, you will see the HAMR hooks in the properties of several A:M object types as "Plugin Properties, HAMR Properties".
 
 Model Interactions- In the Project Work Space (PWS) in A:M, expand the Objects tab and select the particular Model that you want to modify.  View the object properties and select "Plugin Properties" and select "HA:MR" properties. At that point you will see several model interaction flags:
 
 Moveable- If turned "On" allows the WebHAMR user to left click on the object and drab it around in the scene in the ground plane or shift-left click to drag it around in the screen plane.
 
 Turnable- If turned "On" allows the WebHAMR user in "Turn mode" to left click on the object and rotate it in any direction or shift-left click to rotate it around its axis.
 
 Zoomable- If turned "On" allows the WebHAMR user in "Zoom mode" to left click on the object and zoom it or scale it relative to the rest of the scene.
 
 Poseable- If turned "On" allows the WebHAMR user in "Move mode" to click and pose bones in a model.  If the bone is part of an IK chain, the bone will be translated with IK constraints applied.  If the bone is not part of an IK chain, the bone will be rotated. If CTRL-left click, IK chain end translation or bone shaft rotation occurs.  If Alt-left click, IK chain pivot translation or bone roll rotation is applied.  Yeah, this is a bit confusing but play with it a bit to get a feel for it.
   I**********************************************************************************************
 
 Sound- For a particular sound in the Project Work Space (PWS) in A:M, select the sound properties and then select "Plugin Properties" and then select "HAMR Properties".   There you will see two properties that can be set.  The first is "MouseOver Group" and the second is "LButton Group".  If you click on the value field for one or the other of these properties, a list of A:M "Groups" will pop up, sorted by Model.  Selecting one of these groups means that in WebHAMR if the user places the mouse cursor over the "MouseOver Group" or left clicks on the "LButton Group" the sound will be played.  Usually one or the other should be selected, not both. The various time properties shown in the Sound HA:MR properties are not currently used by WebHAMR
 
 The next interactivity information is input at the Pose Relationship level.  The intent of these properties is to allow a pre-exisisting Pose to be transistioned over a particular period of time.  If you don't have a Pose that does what you want done, you'll need to create one before applying these properties. To get to this level, expand the "Objects", expand a particular Object, expand the "Relationships", expand the "User Properties Relationships", select a particular Pose Relationships and expand it, select a particular Relationship and view the properties.  Select "Plugin Properties" and then "HA:MR Properties".  You will then see the interactivity properties you can set for WebHAMR.
 
 These Properties are:
 MouseOverGroup
 LButtonGroup
 Ramp-in Time
 Hold Time
 Ramp-out Time
 Periodic Time
 Random Time
 
 Select a MouseOverGroup or  a LButtonGroup if you want the Pose to be executed based on a mouse event.  Set a Periodic Time if you want the pose to be triggered on a periodic time basis or a Random Time if you want the pose to be triggered on a gaussian random time basis.  Random Time can be used for such things as eyeblink pose executions.  Then for whichever above trigger you selected, set the Ramp-in Time to be how long to take to transition the pose from "0" to "1", Set the Hold Time to how long you want the pose to hold at the "1" position.  Set the Ramp-out Time to be how long to take to transistion back from the "1" position to the "0" position.  The pose transitions are linearly applied with time.
 
 Anything that you can setup a Pose for in A:M can thus be controlled by user interaction in WebHAMR.  Usually a Pose is related to moving the various parts of a character's body, but it can also be used for lights or anything else that A:M allows a Pose to be set up for.
 
 The last level that interactions can be set for is the Action level.  In the PWS select "Actions" and then a particular Action and in that Action properties expand "Plugin Properties" and "HA:MR Properties".  You can select a MouseOverGroup or a LButtonGroup as described above.  If this is done, then the WebHAMR user can mouse over or left click on a Model Group and this will cause the Action to be inserted into the Model in the Choreography.  Then if WebHAMR is in "Play" mode, the action will start animating until the action is removed via another mouse over or left click on the Model Group.  In such a usuage, mouse click is much better than mouse over for triggering.  The various time properties shown in the Action HA:MR properties are not currently used by WebHAMR.
 
 WebHAMR Scripting
 
 The following functions can be implemented in a WebHAMR HTML file in the JavaScript section and will be called by WebHAMR based on particular events.
 For an example of usages, see the Template1.html and Template2.html files that is distributed with WebHAMR.  If you are trying to write your own html files with JavaScript embedded, it is best if you turn on JavaScript error reporting in your browser.  That will at least tell you what line the error is on.  Also, it is best if possible to write and debug the files on your local computer and get them working there prior to transferring to your web server where debugging is more difficult.  The JavaScript "alert" function is useful for testing and debugging your html/javascript files.  The alert function pops up a message box with whatever info you pass to it.  Remember to remove these alert calls before releasing the file for use.
 
 ******************************************************************************************
 <SCRIPT LANGUAGE="JavaScript" FOR="window" EVENT="onload()">
 </SCRIPT>
 
 The above function fires when the WebHAMR program has loaded and is ready to load data.
 
 From within this script function you may call the following function into WebHAMR:
 CWebHAMRCtrl.LoadModel("http://www.hash.com/hamr/KeeKatHAMR.zip")
 where you substitute your own file name.  The purpose of this function is to tell WebHAMR to begin the process of downloading the file from the web, unzipping it, and loading the files included in the zip file.  This function returns immediately to JavaScript but does not indicated that the function has completed.  See the next function for the completion notification.  Don't overlook the '.' period between the CWebHAMRCtrl and LoadModel().
 
 ******************************************************************************************
 <SCRIPT LANGUAGE="JavaScript" FOR="CWebHAMRCtrl" EVENT="OnProjectLoaded(name)">
 </SCRIPT>
 
 The above function fires when the WebHAMR program has completed loading a data file.
 
 From within this script function you may call the following function into WebHAMR:
 CWebHAMRCtrl.DoStartPlay()
 
 This causes the loaded project to start "playing" immediately after loading. Otherwise, the user can click on the "Play" button in the toolbar to start the animation playing, if there is any animation in the project.  Typically you might want to start playing automatically for a project that is intended to be watched similar to a video or film.
 
 Project=CWebHAMRCtrl.GetProject()
 
 This function call returns the HAMR_HProject OLE Automation dispatch interface handle.  See below for more info on SDK function calls.
 
 ******************************************************************************************
 <SCRIPT LANGUAGE="JavaScript" FOR="CWebHAMRCtrl" EVENT="OnLButtonClicked(ModelCache,Group)">
 </SCRIPT>
 
 The above function fires when the WebHAMR program user clicks the left mouse button over a Model (scene object).
 
 From within this script function you may call the following function into WebHAMR:
 CWebHAMRCtrl.DoStartPlay()
 
 This causes the loaded project to start "playing" after the click on the appropriate Model Group.  See Template2.html for an example on how to check for a particular Model and/or Group click.
 
 ************************************************************************************
 <SCRIPT LANGUAGE="JavaScript" FOR="CWebHAMRCtrl" EVENT="OnMouseOver(ModelCache,Group)">
 </SCRIPT>
 
 The above function fires when the WebHAMR program user moves the mouse cursor over a Model (scene object).
 
 ************************************************************************************
 
 Advanced WebHAMR JavaScripting:
 
 You should probably be familar with simple scripting as shown in the samples Template1.html and Template2.html before trying out more advanced scripting.
 In addition to the few WebHAMR functions that can be called via scripts as discussed above, WebHAMR also exposes the entire A:M SDK function set via OLE Automation for usage in scripts.  Just what you do with such scripting is up to you but allows for access to just about anything internally in the loaded project.  In general the WebHAMR SDK function calls are named the same as the A:M SDK function calls but with a "HAMR_" prefix attached to the A:M SDK function.  The difficulty in such scripting is in determining how to begin access into the project data.  So far I have only tried cases where the HAMR_GetProject() function is used to obtain the project dispatch interface handle from which other objects may be obtained by walking the project tree, or by using the HAMR_HModelCache and/or HAMR_HGroup handles passed to JavaScript via the OnMouseMove() and OnLButtonClicked() functions as starting points.  Once again, see the Template1.html and Template2.html sample files, particularly lines that I have commented out with the "//" characters.
 
 One complication of exposing the A:M SDK classes and functions via OLE Automation is that "implementation inheritance" is not supported by OLE Automation. What that means is that if a parent class implements a function, the child class knows nothing of this parent function.  So you will see some cases in the samples where I used a type of casting to get the object to be of the type required by the function.  This is done via the HAMR_CastToClassType() function.  This is somewhat of a pain to work with, particularly in debugging.  If you get a JavaScript error that a line contains a function that is not a member of a class, you can almost bet that you need to look at the SDK and see at what class level this function is defined and do an object cast to that class type before calling the function.