Difference between revisions of "Kits"

From The Foundry MODO SDK wiki
Jump to: navigation, search
(Referencing Other Files)
Line 163: Line 163:
 
     </atom>
 
     </atom>
 
</source>
 
</source>
 +
 +
== Installing a Kit ==
 +
==== OS X Using PackageMaker ====
 +
 +
On OS X, kits should be installed into /Library/Application Support/Luxology/Content/Kits.  This [[File:MacKits.pdf]] document explains how to build a kit installer for modo on OS X.

Revision as of 19:27, 28 November 2012

Introduction

A kit in modo 501 and later versions is a collection of configs, resource images, scripts, plug-ins and content that add a specific set of features to modo. Ideally this is a unified feature set that a user would want to install or uninstall as a unit.

modo finds kits when it searches for configs on startup, and any such directory can contain kits. This includes user:Configs, content:Kits and the main resource directory.

Defining a Kit

A kit is a sub-directory containing a file called index.cfg. This is a normal config file but with a slightly different preamble containing the name of the kit.

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName">        [...]
    </configuration>

The kit name is an internal name (alphanumeric and underscore only, starting with a letter), and must be globally unique. A alias is automatically created for refering to the kit directory, and is called kit_name.

Specific kits can be included or excluded on specific system types. For example, this kit only loads on the PC.

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName" and="nt">        [...]
    </configuration>

This one will load in 32-bit modo and on any Mac.

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName" and="app32" or="mac">        [...]
    </configuration>

The boolean operators are ungrouped and are simply applied in order. Forms like !x86 can also be used for a negative test. The supported keys are:

  • app32 -- 32-bit application on any platform
  • app64 -- 64-bit application on any platform
  • osx, mac -- Macintosh platform
  • win, nt -- Windows platform
  • x86 -- 32-bit Windows
  • x64 -- 64-bit Windows

It's possible to limit kits to specific version or release numbers. This kit will only load in in a version late enough to have a required bug fix. (The xml-safe characters "[" and "]" stand in for the less-than and greater-than operators. "=" also works.)

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName" and="ver]40345">        [...]
    </configuration>
    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName" and="rel=501">        [...]
    </configuration>

Referencing Other Files

Resources

The index.cfg file is the only config file read by default. It can contain all the resources for the kit, or it can import other resources by placing them in a sub-directory of the kit and referencing that with an import directive in the index config.

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName">
 
        <import>resrc</import>
 
        [...]
    </configuration>

Alternately, the index can import specific resource files.

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName">
 
        <import>icons.cfg</import>
        <import>forms.cfg</import>
 
        [...]
    </configuration>

Plug-ins

The kit can also contain plug-ins, which can be found by putting them into a subdirectory and adding auto-scan directives for 32 and/or 64 bits.

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName">
 
        <atom type="Extensions32">
            <list type="AutoScan">extra</list>
        </atom>
        <atom type="Extensions64">
            <list type="AutoScan">extra</list>
        </atom>
 
        [...]
    </configuration>

If the kit contains both Windows plug-ins -- which are compiled separately for 32 and 64 bit -- and Mac fat binaries containing code for both architectures, they can be referenced this way:

    <?xml version="1.0" encoding="UTF-8"?>
    <configuration kit="kitName">
 
        <atom type="Extensions32">
            <list type="AutoScan">win32</list>
            <list type="AutoScan">mac</list>
        </atom>
        <atom type="Extensions64">
            <list type="AutoScan">win64</list>
            <list type="AutoScan">mac</list>
        </atom>
 
        [...]
    </configuration>

The mac plug-ins will be ignored on Windows and vice-versa.

Scripts

Scripts can also be referenced from kits. This is done by defining an alias to the script. If the script is in the root of the kit's directory, nothing beyond the script's name is needed.

    <atom type="ScriptSystem">
        <hash type="ScriptAlias" key="myScript">doit.pl"</hash>
        <hash type="ScriptAlias" key="myScript2">dir/doi2t.pl"</hash>
    </atom>

Once defined, the script alias can be used in place of the path to the script. For example, "@myScript" will execute the above script at "doit.pl", automatically taking into account the alias and the kit's location (or more specifically, the location of the config that the alias is defined in). This will work if the script is called directly by the user (say, from a key mapping they created) or if it is called from within the kit itself.

It is recommended that all scripts used within kits use script aliases to ensure that attempts by the user to map the script to a key will work correctly. An alternative is to execute the script more directly through the kit's path alias, but the script alias is cleaner.

Images

Image resources can also be accessed with relative paths. The image name for an image resource can be relative to the directory that contains the config file making the resource declaration. This fragment defines an icon that could be used for an item type. The key for the image resource has to be globally unique.

    <atom type="UIElements">
 
        <hash type="image" key="testKit_icons">icon.tga</hash>
 
        <hash type="Icon" key="item.val.test.texture">
            <atom type="Source">testKit_icons</atom>
            <atom type="Location">0 0 13 13</atom>
        </hash>
 
    </atom>

Preset Items

Users can also import a kit directory to modo's preset browser through the kit config file. This allows preset items contained within the kit to appear within modo's preset browser without the need to manually add the directory. Each identified directory should be followed with a sequential index number. This fragment will add the folders "MyMaterials" and "MyMeshes" contained in the testKit root folder to modo's preset browser.

    <atom type="DirBrowser">
        <hash type="ClientPath" key="presetChoice@kit_testKit:MyMaterials">1</hash>
        <hash type="ClientPath" key="presetChoice@kit_testKit:MyMeshes">2</hash>
    </atom>

Installing a Kit

OS X Using PackageMaker

On OS X, kits should be installed into /Library/Application Support/Luxology/Content/Kits. This File:MacKits.pdf document explains how to build a kit installer for modo on OS X.