Modifying Morphyre

Morphyre Personal cannot be easily modified so if you want to create your own scenes or script it, you must use Morphyre Pro...

Overview

Morphyre can be modified in three areas - changing the Colour Schemes with Xml, creating completely new scenes, or scripting Morphyre to make it change scenes in different ways...

Colour Schemes

If you look in the scenes folder in Morphyre Pro you'll see a bunch of large Xml files. These contain all the different colour schemes for each type of scene. Just changing the text in these or adding more elements will easily create new scenes and will be flexible enough for most people.

The XML File Format

An XML file consists of a <SceneList> element containing one or more <Scene> Elements. See Tutorial 1 for a very simple example. For more information about the contents see the Colour Scheme Xml Documentation.

Modifying the XML

There are plenty of tools available for dealing with XML Efficiently. XML Notepad is a great place to start. It also contains support for XPath and XSLT, which with a little effort will let you create hundreds of new Colour Schemes very easily - if in any doubt ask on the forums.

You don't need to name your XML file in any special way, you just need to put it in the scenes folder and next time Morphyre starts, all those new scenes will be pulled in and will appear in the UI.

Scene Creation

Scene code is stored in the scenes directory as .pur3c files, and header files for scene components are stored in .pur3h files (these don't come with Morphyre, but Documentation of them is provided). When compiled the files are pur3s files, which are either in the scenes\bin folder or in compressed .morpharch files (these can store a scene as well as all images and models it needs).

A Pur3s file by itself can't be used in Morphyre. An XML file also exists which describes a scene completely - which Pur3s file it uses, and also various data items that are read by Morphyre and the Scene. For example, the 'Bigfoot' scene has just one Pur3s file and one XML file, however there are over one hundred colour schemes, all of which are described in the XML file. You can modify the XML files to add new scenes with different foregrounds and backgrounds without ever having to compile a new scene - see 'Colour Schemes' above.

File formats

Scenes can use .jpg and .png files for images (.png files can also be transparent in places). If a texture filename is specified for a skybox, you can insert a '*' character, and the skybox will automatically load all 6 images by inserting front/back/top/bottom/left/right where the * is.

Where images are loaded by scenes, a semicolon (';') can be added after the filename and a series of JavaScript commands executed, which will modify the image after it is loaded but before it is pulled into a texture. The available commands are:

function resize(width,height,col) // resize canvas and fill what's left with col
function scale(width,height) // rescale image
function matrix(a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t) // apply a 5x4 matrix to RGBA1 (REALLY flexible)
function hue(h) // adjust hue -1 <= h <= 1
function blur(radius) // box blur image by the given radius (SLOW)

function blurCh(radius,r,g,b,a) // box blur image by the given radius (SLOW) on only the channels that are nonzero
function atoc() // convert alpha channel to colour channel

function grey() // convert to greyscale

function flip() // flip the image upside-down

Note that matrix takes a 5x4 colour matrix (there is plenty of information about these on the internet, but try here for starters). A lot of the examples around use a 5x5 matrix (but we ignore the rightmost column), or a 4x4 matrix (usually because they only change RGB, not RGBA).

for example:

huemap.png;matrix(8,0,0,0,-4,8,0,0,0,-4,8,0,0,0,-4,0,0,0,1,0);

Loads huemap.png, then applies a matrix which makes it greyscale from what was on the Red channel with a huge contrast

For Videos, you can also add optional commands after a semi colon too. These are as follows:

loop=1 // force this video to loop

audio=1 // force audio to be played for this video

alpha=1 // (windows only) force the alpha channel to be used for this video, even if DirectShow says it doesn't exist

3D Models are stored as raw triangle data. This is a series of floating point numbers, and the file extension gives a hint as to what the file contains (it corresponds to a built-in type). For example, a '.n3v3' file contains 6 floats per vertex, X, Y and Z for a normal, followed by X, Y and Z for the vertex position - and it corresponds to the N3V3 built-in type.

We have a tool available here for creating, viewing and manipulating these models.

Creating a new scene

To create a new scene you're best off starting from one of the original scenes for now. Find a scene you like, then copy the .pur3c file from the scenes directory to another filename, for instance myscene.pur3c. Look in the XML file with the same name as your scene and copy the <SceneList> tag with just one of the <Scene> XML elements, renaming anything that references the old scene to reference the new scene.

You can then compile the Pur3c file by going into the Morphyre directory and typing 'morphyre_compile scenes\myscene.pur3c' - this'll create a myscene.morpharch file on success. While you can now go into the Morphyre UI and select your scene, you can also start morphyre ensuring that you view *only* your scene using one of the following commands:

R5 -xml myscene.xml:

This will load the scene as with any colour schemes in the relevant XML file.

R5 -id myscene_id:

This will load the single colour scheme in your XML file given by myscheme_id - note that this must match the Scene ID attribute in the XML.

For information on what code is available and how to use it, see the Morphyre Scene Pur3h Documentation. A set of Tutorials are also available

Scene Control

Morphyre contains a minimal JavaScript interpreter called TinyJs. This executes JavaScript which chooses which scenes play when, as well as handling keypresses and mouse movement. The code in key.js is executed first, followed by any JavaScript (.js) files in the data directory starting with a digit (in numerical order).

010_main.js contains the main handlers for Morphyre events (normally governed by the user interface). If you wish to make a slideshow that runs without the user interface, this is what you would need to alter.

The commands available from JavaScript are documented here