HOME | DD

Description
Foreword:
I know I'm supposed to be making the second part of PMX Explained, but I've been swamped with programming stuff. Since HLSL is essentially C++, I thought, why not do something that's useful and fun? And so I decided to make this non-exhaustive documentation on the CONTROLOBJECT class. The terms written in italic will be explained at the bottom.

MME effects are written in HLSL. It is a derivative of C++, meaning it uses the same syntax, operators, and some functions. FX files are plain text files with UTF-8 encoding. Although you can edit them with Notepad, I highly recommend getting a better alternative, such as PSPad (which I use) or Notepad++. MME detects changes in loaded FX files, and will reload them if told so. Errors in the code will trigger an error message in MMD.

Why do I write CONTROLOBJECT in all-caps? C++, unlike Pascal, is case-sensitive. "CONTROLOBJECT" is correct, but "Controlobject" and "controlobject" are not.

Using CONTROLOBJECT
CONTROLOBJECT is a class used for controlling effects by interfacing objects in MMD with them. For example, you can control a property of an effect with a slider on a model.
CONTROLOBJECT, when used properly, returns the value of what it is set to return, be it the position of a slider, the transparency of an accessory, or using a child class, the colour and direction of light.
To use CONTROLOBJECT, you must define a variable with the class as value, as follows:

Type Name : CONTROLOBJECT< Parameters >;

where:
Type is the variable's data type (float, float3, boolean, etc),
Name is the variable's identifier, and
Parameters is the list of parameters, each of which must be defined as strings and end with a semicolon.

Example:
float3 AccAngles : CONTROLOBJECT< string name="EffectController.x"; string item="Rxyz"; >;
This one sets "AccAngles" to the X-Y-Z angles of "EffectController.x".

Parameters
Parameters must always be strings. The list of parameters, with which we tell the class what it should return, nearly always has the "name" property. It tells the class which object it refers to. It is either the full filename (e.g. "Miku_Hatsune.pmd"), or the name of an internal object (e.g. "Light").
The second parameter is optional. It usually tells the class what property it should return.
If not set, and the assigned variable is a boolean type, it simply checks the existence of the referred object, returning True if it exists and False if it does not. If not set and preceeded by a non-boolean variable, it returns a default value. It is usually the position as a float3 value.

A non-exhaustive list of properties I've found for accessories (with their types):
(not set): position in 3D space (float3)
(not set): existence (boolean)
X: position on the X axis (float)
Y: position on the Y axis (float)
Z: position on the Z axis (float)
Rxyz: rotation values (float3)
Tr: transparency, ranging from 0.0 to 1.0 (float)
Si: scale, ranging from 0.0 to positive infinity (float)

...and models:
(not set): existence (boolean)
Any name given to a morph: the slider's position, from 0.0 to 1.0 (float). Important: the name must be the Japanese one, NOT English.

Child classes:
Inheritance, the blessing of classes. There are classes that inherit the members of CONTROLOBJECT. They are mostly used with internal objects and geometry. Their only property is usually Object.
Usage:
Type Name : CLASS_NAME < string Object="Name"; >;

DIRECTION (float3): returns the object's angles.
POSITION (float3): returns the object's position in 3D space.
DIFFUSE (float4): returns the RGBA values of the object's diffuse colour.
SPECULAR (float3): returns the object's specular RGB colour.
SPECULARPOWER (float): returns the object's shininess.
AMBIENT (float3): returns the object's ambient RGB colour.
EMISSIVE (float3): returns the object's emissive RGB colour.

Objects to use with these:
Light: global directional light
Geometry: the vertex geometry. I don't know how to use this one, though.
Camera: the camera, duh.

There are, of course, many other classes, but I haven't been able to figure them out.

Footnotes:
Declaration: type, followed by an identifier. It allocates an adequate amount of memory for the variable.
Definition: type, followed by an identifier and an assignment. It declares a variable, then gives it an initial value.
Class: a data type that includes its own set of properties and methods (collectively: members)
Object: essentially the same as the class. Here, they are the models, accessories and other things that make up a scene in MMD.
Property: a variable within a class or object.
Return: when a function is assigned to a variable (Var = function()), the variable is given the value returned by the function.
Morph: also called a slider or an expression.
Inheritance: child classes can inherit certain members of their parents. For example, in C++, fstream inherits members of iostream, which inherits members of istream. Because of this inheritance, fstream inherited the members of istream.

Types:
int: 4-byte signed integer value.
float: 4-byte floating point value. In layman's terms, real numbers.
float3: vector with three float values (x, y, z).
float4: vector with four float values (x, y, z, w).
float4x4: 4 by 4 float matrix.
bool: boolean (logic) type, true or false.

Description
Foreword:
I know I'm supposed to be making the second part of PMX Explained, but I've been swamped with programming stuff. Since HLSL is essentially C++, I thought, why not do something that's useful and fun? And so I decided to make this non-exhaustive documentation on the CONTROLOBJECT class. The terms written in italic will be explained at the bottom.

MME effects are written in HLSL. It is a derivative of C++, meaning it uses the same syntax, operators, and some functions. FX files are plain text files with UTF-8 encoding. Although you can edit them with Notepad, I highly recommend getting a better alternative, such as PSPad (which I use) or Notepad++. MME detects changes in loaded FX files, and will reload them if told so. Errors in the code will trigger an error message in MMD.

Why do I write CONTROLOBJECT in all-caps? C++, unlike Pascal, is case-sensitive. "CONTROLOBJECT" is correct, but "Controlobject" and "controlobject" are not.

Using CONTROLOBJECT
CONTROLOBJECT is a class used for controlling effects by interfacing objects in MMD with them. For example, you can control a property of an effect with a slider on a model.
CONTROLOBJECT, when used properly, returns the value of what it is set to return, be it the position of a slider, the transparency of an accessory, or using a child class, the colour and direction of light.
To use CONTROLOBJECT, you must define a variable with the class as value, as follows:

Type Name : CONTROLOBJECT< Parameters >;

where:
Type is the variable's data type (float, float3, boolean, etc),
Name is the variable's identifier, and
Parameters is the list of parameters, each of which must be defined as strings and end with a semicolon.

Example:
float3 AccAngles : CONTROLOBJECT< string name="EffectController.x"; string item="Rxyz"; >;
This one sets "AccAngles" to the X-Y-Z angles of "EffectController.x".

Parameters
Parameters must always be strings. The list of parameters, with which we tell the class what it should return, nearly always has the "name" property. It tells the class which object it refers to. It is either the full filename (e.g. "Miku_Hatsune.pmd"), or the name of an internal object (e.g. "Light").
The second parameter is optional. It usually tells the class what property it should return.
If not set, and the assigned variable is a boolean type, it simply checks the existence of the referred object, returning True if it exists and False if it does not. If not set and preceeded by a non-boolean variable, it returns a default value. It is usually the position as a float3 value.

A non-exhaustive list of properties I've found for accessories (with their types):
(not set): position in 3D space (float3)
(not set): existence (boolean)
X: position on the X axis (float)
Y: position on the Y axis (float)
Z: position on the Z axis (float)
Rxyz: rotation values (float3)
Tr: transparency, ranging from 0.0 to 1.0 (float)
Si: scale, ranging from 0.0 to positive infinity (float)

...and models:
(not set): existence (boolean)
Any name given to a morph: the slider's position, from 0.0 to 1.0 (float). Important: the name must be the Japanese one, NOT English.

Child classes:
Inheritance, the blessing of classes. There are classes that inherit the members of CONTROLOBJECT. They are mostly used with internal objects and geometry. Their only property is usually Object.
Usage:
Type Name : CLASS_NAME < string Object="Name"; >;

DIRECTION (float3): returns the object's angles.
POSITION (float3): returns the object's position in 3D space.
DIFFUSE (float4): returns the RGBA values of the object's diffuse colour.
SPECULAR (float3): returns the object's specular RGB colour.
SPECULARPOWER (float): returns the object's shininess.
AMBIENT (float3): returns the object's ambient RGB colour.
EMISSIVE (float3): returns the object's emissive RGB colour.

Objects to use with these:
Light: global directional light
Geometry: the vertex geometry. I don't know how to use this one, though.
Camera: the camera, duh.

There are, of course, many other classes, but I haven't been able to figure them out.

Footnotes:
Declaration: type, followed by an identifier. It allocates an adequate amount of memory for the variable.
Definition: type, followed by an identifier and an assignment. It declares a variable, then gives it an initial value.
Class: a data type that includes its own set of properties and methods (collectively: members)
Object: essentially the same as the class. Here, they are the models, accessories and other things that make up a scene in MMD.
Property: a variable within a class or object.
Return: when a function is assigned to a variable (Var = function()), the variable is given the value returned by the function.
Morph: also called a slider or an expression.
Inheritance: child classes can inherit certain members of their parents. For example, in C++, fstream inherits members of iostream, which inherits members of istream. Because of this inheritance, fstream inherited the members of istream.

Types:
int: 4-byte signed integer value.
float: 4-byte floating point value. In layman's terms, real numbers.
float3: vector with three float values (x, y, z).
float4: vector with four float values (x, y, z, w).
float4x4: 4 by 4 float matrix.
bool: boolean (logic) type, true or false.