MilkShape 3D 1.8.5. Plugin SDK (WIN32)

[D.J.Peters]

wikipedia: https://en.wikipedia.org/wiki/Milkshape_3D

homepage: http://www.milkshape3d.com

MilkShape 3D: ms3d185beta1.zip

Joshy

file: msModelLib.bi

Code: Select all

#ifndef __MSMODELLIB_BI__
#define __MSMODELLIB_BI__

' MilkShape 3D Model Plugin Import/Export/Tool API (for version 1.8.4 and up).

#inclib "msModelLib"

extern "C"

' Constants
#define MS_MAX_NAME   32
#define MS_MAX_PATH   256

#define MAX_VERTICES	65534
#define MAX_TRIANGLES	65534
#define MAX_GROUPS		255
#define MAX_MATERIALS	128
#define MAX_JOINTS		128

' Types
type msVec2
  as single u,v
end type  
type msVec3
  as single x,y,z
end type

'type msVec4
'  as single x,y,z,w
'end type

type msColor
  declare constructor(r as single=0,g as single=0,b as single=0,a as single=1)
  declare operator *=(s as single)
  as single r,g,b,a
end type
constructor msColor (pr as single,pg as single,pb as single,pa as single)
  r=pr:g=pg:b=pg:a=pa
end constructor
operator msColor . *= (s as single)
 r*=s : g*=s : b*=s
end operator

operator +(cl as msColor, cr as msColor) as msColor
  return type(cl.r+cr.r, cl.g+cr.g, cl.b+cr.b)
end operator
operator *(c as msColor, s as single) as msColor
  return type(c.r*s, c.g*s, c.b*s, c.a)
end operator 

function FadeRGB(cl as msColor, cr as msColor, t as single) as msColor
  if t<=0 then return cl
  if t>=1 then return cr
  dim as single tt=1-t
  return cl*(1-t) + cr*t 
end function


' msFlag
type msFlag as long
' eSelected = It is selected from the normal windows (front/back, top/bottom, left/right, 3d).
const as msFlag eSelected     = &H01
' eSelected2 = It is selected in the texture coordinator editor.
const as msFlag eSelected2    = &H02
' eHidden = The object is hidden. (Hide - Ctrl H has been done when these vertices were selected)
const as msFlag eHidden       = &H04
' eDirty = There is changes that have yet to be saved. (this is so that the autosave when closing works correctly)
const as msFlag eDirty        = &H08
const as msFlag eAveraged     = &H10
const as msFlag eKeepVertex   = &H20

' material flags
const as msFlag eIgnoreAlpha  = &H10
const as msFlag eCombineAlpha = &H20
const as msFlag eHasAlpha     = &H40
const as msFlag eSphereMap    = &H80


' ##########################
' # MilkShape 3D interface #
' ##########################
' a milkshape 3d scene has one model
type msModel       : as long dummy : end type 
  ' a model can have a collection of materials
  type msMaterial    : as long dummy : end type
  ' a model can have a collection of joints/bones  
  type msBone        : as long dummy : end type
    ' a bone can have a collection of position and rotation keys
    type msPositionKey : as long dummy : end type
    type msRotationKey : as long dummy : end type
  
  ' a model can have a collection of meshes
  type msMesh        : as long dummy : end type
    ' a mesh can have a collection of vertices
    type msVertex      : as long dummy : end type
    type msVertexEx    : as long dummy : end type
    ' a mesh can have a collection of triangles
    type msTriangle    : as long dummy : end type 
    type msTriangleEx  : as long dummy : end type  


' ###########
' # msModel #
' ###########
declare function msModel_GetModelVersion(byval pModel as msModel ptr) as long
declare sub      msModel_Destroy        (byval pModel as msModel ptr)

declare sub      msModel_SetComment    (byval pModel as msModel ptr, byval pszComment as const zstring ptr)
declare function msModel_GetComment    (byval pModel as msModel ptr, byval pszComment as zstring ptr, byval nMaxCommentLength as long) as long

declare function msModel_SetFrame      (byval pModel as msModel ptr, byval nFrame as long) as long
declare function msModel_GetFrame      (byval pModel as msModel ptr) as long

declare function msModel_SetTotalFrames(byval pModel as msModel ptr, byval nTotalFrames as long) as long
declare function msModel_GetTotalFrames(byval pModel as msModel ptr) as long

declare sub      msModel_SetPosition   (byval pModel as msModel ptr, byref Position as msVec3)
declare sub      msModel_GetPosition   (byval pModel as msModel ptr, byref Position as msVec3)

declare sub      msModel_SetRotation   (byval pModel as msModel ptr, byref Rotation as msVec3)
declare sub      msModel_GetRotation   (byval pModel as msModel ptr, byref Rotation as msVec3)

declare sub      msModel_SetCamera     (byval pModel as msModel ptr, byref Position as msVec3, byref RotationXY as msVec2)
declare sub      msModel_GetCamera     (byval pModel as msModel ptr, byref Position as msVec3, byref RotationXY as msVec2)

declare sub      msModel_SetFileName   (byval pModel as msModel ptr, byval pszFileName as const zstring ptr)
declare function msModel_GetFileName   (byval pModel as msModel ptr, byval pszFileName as zstring ptr, byval nMaxFileNameLength as long) as long


' ##############
' # msMaterial #
' ##############
declare function msModel_FindMaterialByName(byval pModel as msModel ptr, byval szName as const zstring ptr) as long
declare function msModel_AddMaterial       (byval pModel as msModel ptr) as long
declare function msModel_GetMaterialCount  (byval pModel as msModel ptr) as long

declare function msModel_GetMaterialAt     (byval pModel as msModel ptr, byval nIndex as long) as msMaterial ptr
declare sub      msMaterial_Destroy        (byval pMaterial as msMaterial ptr)

declare sub      msMaterial_SetComment     (byval pMaterial as msMaterial ptr, byval pszComment as const zstring ptr)
declare function msMaterial_GetComment     (byval pMaterial as msMaterial ptr, byval pszComment as zstring ptr, byval nMaxCommentLength as long) as long

'eIgnoreAlpha eCombineAlpha eHasAlpha eSphereMap
declare sub      msMaterial_SetFlags       (byval pMaterial as msMaterial ptr, byval nFlags as long)
declare function msMaterial_GetFlags       (byval pMaterial as msMaterial ptr) as long

declare sub      msMaterial_SetName        (byval pMaterial as msMaterial ptr, byval szName as const zstring ptr)
declare sub      msMaterial_GetName        (byval pMaterial as msMaterial ptr, byval szName as zstring ptr, byval nMaxLength as long)

declare sub      msMaterial_SetAmbient     (byval pMaterial as msMaterial ptr, byref Ambient as msColor)
declare sub      msMaterial_GetAmbient     (byval pMaterial as msMaterial ptr, byref Ambient as msColor)

declare sub      msMaterial_SetDiffuse     (byval pMaterial as msMaterial ptr, byref Diffuse as msColor)
declare sub      msMaterial_GetDiffuse     (byval pMaterial as msMaterial ptr, byref Diffuse as msColor)

declare sub      msMaterial_SetSpecular    (byval pMaterial as msMaterial ptr, byref Specular as msColor)
declare sub      msMaterial_GetSpecular    (byval pMaterial as msMaterial ptr, byref Specular as msColor)

declare sub      msMaterial_SetEmissive    (byval pMaterial as msMaterial ptr, byref Emissive as msColor)
declare sub      msMaterial_GetEmissive    (byval pMaterial as msMaterial ptr, byref Emissive as msColor)
' 0.0 - 128.0
declare sub      msMaterial_SetShininess   (byval pMaterial as msMaterial ptr, byval fShininess as single)
declare function msMaterial_GetShininess   (byval pMaterial as msMaterial ptr) as single
' 0.0 - 1.0
declare sub      msMaterial_SetTransparency(byval pMaterial as msMaterial ptr, byval fTransparency as single)
declare function msMaterial_GetTransparency(byval pMaterial as msMaterial ptr) as single

declare sub      msMaterial_SetDiffuseTexture      (byval pMaterial as msMaterial ptr, byval szDiffuseTexture as const zstring ptr)
declare sub      msMaterial_GetDiffuseTexture      (byval pMaterial as msMaterial ptr, byval szDiffuseTexture as zstring ptr, byval nMaxLength as long)

declare sub      msMaterial_SetDiffuseTextureWidth (byval pMaterial as msMaterial ptr, byval nWidth as long)
declare function msMaterial_GetDiffuseTextureWidth (byval pMaterial as msMaterial ptr) as long

declare sub      msMaterial_SetDiffuseTextureHeight(byval pMaterial as msMaterial ptr, byval nHeight as long)
declare function msMaterial_GetDiffuseTextureHeight(byval pMaterial as msMaterial ptr) as long

declare sub      msMaterial_SetAlphaTexture (byval pMaterial as msMaterial ptr, byval szAlphaTexture as const zstring ptr)
declare sub      msMaterial_GetAlphaTexture (byval pMaterial as msMaterial ptr, byval szAlphaTexture as zstring ptr, byval nMaxLength as long)


' ##########
' # msBone #
' ##########
declare function msModel_FindBoneByName(byval pModel as msModel ptr, byval szName as const zstring ptr) as long

declare function msModel_AddBone       (byval pModel as msModel ptr) as long
declare function msModel_GetBoneCount  (byval pModel as msModel ptr) as long

declare function msModel_GetBoneAt     (byval pModel as msModel ptr, byval nIndex as long) as msBone ptr
declare sub      msBone_Destroy      (byval pBone as msBone ptr)

declare sub      msBone_SetComment         (byval pBone as msBone ptr, byval pszComment as const zstring ptr)
declare function msBone_GetComment         (byval pBone as msBone ptr, byval pszComment as zstring ptr, byval nMaxCommentLength as long) as long 

declare sub      msBone_SetFlags     (byval pBone as msBone ptr, byval nFlags as long)
declare function msBone_GetFlags     (byval pBone as msBone ptr) as long

declare sub      msBone_SetName      (byval pBone as msBone ptr, byval szName as const zstring ptr)
declare sub      msBone_GetName      (byval pBone as msBone ptr, byval szName as zstring ptr, byval nMaxLength as long)

declare sub      msBone_SetParentName(byval pBone as msBone ptr, byval szParentName as const zstring ptr)
declare sub      msBone_GetParentName(byval pBone as msBone ptr, byval szParentName as zstring ptr, byval nMaxLength as long)

declare sub      msBone_SetPosition  (byval pBone as msBone ptr, byref Position as msVec3)
declare sub      msBone_GetPosition  (byval pBone as msBone ptr, byref Position as msVec3)

declare sub      msBone_SetRotation (byval pBone as msBone ptr, byref Rotation as msVec3)
declare sub      msBone_GetRotation (byval pBone as msBone ptr, byref Rotation as msVec3)

declare function msBone_GetPositionKeyCount(byval pBone as msBone ptr) as long
declare function msBone_AddPositionKey     (byval pBone as msBone ptr, byval fTime as single, byref Position as msVec3) as long
declare function msBone_GetPositionKeyAt   (byval pBone as msBone ptr, byval nIndex as long) as msPositionKey ptr
declare sub      msBone_RemovePositionKeyAt(byval pBone as msBone ptr, byval nIndex as long)

declare function msBone_GetRotationKeyCount(byval pBone as msBone ptr) as long
declare function msBone_AddRotationKey     (byval pBone as msBone ptr, byval fTime as single, byref Rotation as msVec3) as long
declare function msBone_GetRotationKeyAt   (byval pBone as msBone ptr, byval nIndex as long) as msRotationKey ptr
declare sub      msBone_RemoveRotationKeyAt(byval pBone as msBone ptr, byval nIndex as long)


' ############
' # msVertex #
' ############
declare function msMesh_GetVertexCount(byval pMesh as msMesh ptr) as long
declare function msMesh_AddVertex     (byval pMesh as msMesh ptr) as long
declare function msMesh_GetVertexAt   (byval pMesh as msMesh ptr, byval nIndex as long) as msVertex ptr

' eSelected  eSelected2  eHidden
declare sub      msVertex_SetFlags    (byval pVertex as msVertex ptr, byval nFlags as ubyte)
declare function msVertex_GetFlags    (byval pVertex as msVertex ptr) as ubyte

declare sub      msVertex_SetVertex   (byval pVertex as msVertex ptr, byref Vertex as msVec3)
declare sub      msVertex_GetVertex   (byval pVertex as msVertex ptr, byref Vertex as msVec3)

declare sub      msVertex_SetTexCoords(byval pVertex as msVertex ptr, byref st as msVec2)
declare sub      msVertex_GetTexCoords(byval pVertex as msVertex ptr, byref st as msVec2)
' -1 none
declare function msVertex_SetBoneIndex(byval pVertex as msVertex ptr, byval nBoneIndex as long) as long
declare function msVertex_GetBoneIndex(byval pVertex as msVertex ptr) as long

' ##############
' # msTriangle #
' ##############
declare function msMesh_AddTriangle     (byval pMesh as msMesh ptr) as long
declare function msMesh_GetTriangleCount(byval pMesh as msMesh ptr) as long
declare function msMesh_GetTriangleAt   (byval pMesh as msMesh ptr, byval nIndex as long) as msTriangle ptr

declare sub      msTriangle_SetFlags         (byval pTriangle as msTriangle ptr, byval nFlags as ushort)
declare function msTriangle_GetFlags         (byval pTriangle as msTriangle ptr) as ushort

declare sub      msTriangle_SetVertexIndices (byval pTriangle as msTriangle ptr, nIndices() as ushort)
declare sub      msTriangle_GetVertexIndices (byval pTriangle as msTriangle ptr, nIndices() as ushort)

declare sub      msTriangle_SetNormalIndices (byval pTriangle as msTriangle ptr, nNormalIndices() as ushort)
declare sub      msTriangle_GetNormalIndices (byval pTriangle as msTriangle ptr, nNormalIndices() as ushort)

declare sub      msTriangle_SetSmoothingGroup(byval pTriangle as msTriangle ptr, byval nSmoothingGroup as ubyte)
declare function msTriangle_GetSmoothingGroup(byval pTriangle as msTriangle ptr) as ubyte

' ##############
' # msVertexEx #
' ##############
declare function msMesh_GetVertexExAt     (byval pMesh as msMesh ptr, byval nIndex as long) as msVertexEx ptr
declare function msVertexEx_SetBoneIndices(byval pVertex as msVertexEx ptr, byval nIndex as long, byval nBoneIndex as long) as long
declare function msVertexEx_GetBoneIndices(byval pVertex as msVertexEx ptr, byval nIndex as long) as long

declare function msVertexEx_SetBoneWeights(byval pVertex as msVertexEx ptr, byval nIndex as long, byval nWeight as long) as long
declare function msVertexEx_GetBoneWeights(byval pVertex as msVertexEx ptr, byval nIndex as long) as long

declare function msVertexEx_SetExtra      (byval pVertex as msVertexEx ptr, byval nIndex as long, byval nExtra as ulong ) as ulong
declare function msVertexEx_GetExtra      (byval pVertex as msVertexEx ptr, byval nIndex as long) as ulong

' ################
' # msTriangleEx #
' ################
declare function msMesh_GetTriangleExAt  (byval pMesh as msMesh ptr, byval nIndex as long) as msTriangleEx ptr
declare sub      msTriangleEx_SetNormal  (byval pTriangle as msTriangleEx ptr, byval nIndex as long, byref Normal as msVec3)
declare sub      msTriangleEx_GetNormal  (byval pTriangle as msTriangleEx ptr, byval nIndex as long, byref Normal as msVec3)

declare sub      msTriangleEx_SetTexCoord(byval pTriangle as msTriangleEx ptr, byval nIndex as long, byref TexCoord as msVec2)
declare sub      msTriangleEx_GetTexCoord(byval pTriangle as msTriangleEx ptr, byval nIndex as long, byref TexCoord as msVec2)


' ##########
' # msMesh #
' ##########
declare function msModel_FindMeshByName (byval pModel as msModel ptr, byval szName as const zstring ptr) as long
declare function msModel_AddMesh        (byval pModel as msModel ptr) as long
declare function msModel_GetMeshCount   (byval pModel as msModel ptr) as long

declare function msModel_GetMeshAt      (byval pModel as msModel ptr, byval nIndex as long) as msMesh ptr
declare sub      msMesh_Destroy         (byval pMesh as msMesh ptr)

declare sub      msMesh_SetComment      (byval pMesh as msMesh ptr, byval pszComment as const zstring ptr)
declare function msMesh_GetComment      (byval pMesh as msMesh ptr, byval pszComment as zstring ptr, byval nMaxCommentLength as long) as long

declare sub      msMesh_SetFlags        (byval pMesh as msMesh ptr, byval nFlags as ubyte)
declare function msMesh_GetFlags        (byval pMesh as msMesh ptr) as ubyte

declare sub      msMesh_SetName         (byval pMesh as msMesh ptr, byval szName as const zstring ptr)
declare sub      msMesh_GetName         (byval pMesh as msMesh ptr, byval szName as zstring ptr, byval nMaxLength as long)

declare sub      msMesh_SetMaterialIndex(byval pMesh as msMesh ptr, byval nIndex as long)
declare function msMesh_GetMaterialIndex(byval pMesh as msMesh ptr) as long

declare function msMesh_GetVertexNormalCount(byval pMesh as msMesh ptr) as long
declare function msMesh_AddVertexNormal     (byval pMesh as msMesh ptr) as long

declare sub      msMesh_SetVertexNormalAt   (byval pMesh as msMesh ptr, byval nIndex as long, byref Normal as msVec3)
declare sub      msMesh_GetVertexNormalAt   (byval pMesh as msMesh ptr, byval nIndex as long, byref Normal as msVec3)

end extern 

#endif ' __MSMODELLIB_BI__

file: msPlugin.bi

Code: Select all

#ifndef __MSPLUGIN_BI__
#define __MSPLUGIN_BI__

#include once "msModelLib.bi"

' return the kind of plugin via Plugin_GetType()
type PluginType as long
const as PluginType eTypeImport  = &H0001
const as PluginType eTypeExport  = &H0002
const as PluginType eTypeTool    = &H0003
const as PluginType eTypeEdit    = &H0004
const as PluginType eTypeVertex  = &H0005
const as PluginType eTypeFace    = &H0006
const as PluginType eTypeAnimate = &H0007
' can be ored with plugin type
const as PluginType NormalsAndTexCoordsPerTriangleVertex = &H0080

type PluginError as long
const as PluginError eOK    = 0
const as PluginError eError = -1

' the milkshape plugin interface
type msPlugin
  ' implement it as empty sub (don't touch the pointer)
  as sub (byval baseclass as const any ptr) BaseConstructor
  ' return the type of your plugin (eTypeImport, eTypeExport, eTypeTool, eTypeEdit, eTypeVertex, eTypeFace, eTypeAnimate)
  as function as PluginType GetType
  ' return a const pointer of the string showed in the milkshape menu (import/export/tool/edit/vertex/face/animation)
  as function as const zstring ptr GetTitle
  ' run your plugin on the one and only Milkshape 3D model (with all materials, bones, meshes ...)
  as function (byval model as msModel ptr) as PluginError Execute
end type

' implement and "export" te "CreatePlugIn" function without any name decoaration !
extern "Windows-MS"

declare function CreatePlugIn as msPlugin ptr ptr

end extern

#endif ' __MSPLUGIN_BI__

[D.J.Peters]

A short test ToolPlugin that create a simple red material.
"fbc -dll msToolRed.bas"

Joshy

TIP: To test ms3d I wrote many plugins to make it simple I put the two *.bi and my msXXXPlugin.bas files direct in the MilkShape 3D folder !

file msToolRed.bas

Code: Select all

#if not defined(__FB_WIN32__) or defined(__FB_64BIT__) or (__FB_OUT_DLL__ = 0)
 #error 666: this source code must be compiled as 32-bit Windows DLL !
#endif

#include "msPlugin.bi"

dim shared as msPlugin ptr pPlugin

' implement the msPlugin interface

' this are called from milkshape at first
sub BaseConstructor(byval baseclass as const any ptr)
  ' don't touch the pointer in any way !
end sub  

' than milkshape aask for the type of plugin
' return eTypeImport or eTypeExport or eTypeTool or eTypeEdit or eTypeVertex or eTypeFace or eTypeAnimate
function GetType () as PluginType
  return eTypeTool
end function

' be shure the string where GetTitle points to exists the whole runtime of Milkshape3D
' if not and milkshape will show the string in any of the menus it will crash !
function GetTitle () as const zstring ptr
  return @"add a color"
end function

' run your plugin on the "one and only" Milkshape 3D "model"
' return eOK or eError 
function Execute (byval model as msModel ptr) as PluginError
  ' should never happen how ever tell Milkshape 3D something is wrong !
  if model=0 then return eError
  
  ' for testing add a "red" color material to the model
  ' but only if it does not exists (your plugin was executed before)
  var index = msModel_FindMaterialByName(model, "diffuse red")
  ' if "red" does not exist add one
  if index<0 then
    ' create a new material and get it index
    index = msModel_AddMaterial(model)
    var material = msModel_GetMaterialAt(model, index)
    msMaterial_SetComment(material, "A simple diffuse red material created via plugin")
    msMaterial_SetName(material,"diffuse red")
    var dif = msColor(1,0,0,1)
    msMaterial_SetDiffuse(material,dif)
    ' you can set many other properties take a look at "msModel.bi"
  end if  
  
  ' +++ Important news +++ Important news +++ Important news +++
  ' if your plugin is an model exporter (and only than)
  ' you got a copy of the model that means you have to destroy the copy on end !
  if GetType()=eTypeExport then msModel_Destroy(model)
  
  ' tell milkshape the excution of the plugin was OK
  return eOk
end function

' if the DLL loaded by milkshape create and fill the plugin interface 
sub _load_dll_ constructor
  pPlugin = new msPlugin
  pPlugin->BaseConstructor = @BaseConstructor
  pPlugin->GetType         = @GetType
  pPlugin->GetTitle        = @GetTitle
  pPlugin->Execute         = @Execute
end sub
' optional but good coding style if the DLL are unloaded from memory
' free all resources you allocated and the plugin interface it self. 
sub _unload_dll_ destructor
  if pPlugin then delete pPlugin : pPlugin = 0
end sub

' export the CreatePlugIn function without any "decoration@0" !
extern "Windows-MS"
' the one and only exported function
function CreatePlugIn as msPlugin ptr ptr export
  return @pPlugin
end function

end extern

[D.J.Peters]

You can find the tool plugin in the tool menu of ms3d.

The simple plugin add a red diffuse color in the materal section.

[D.J.Peters]

Looks like it's a kind of standard to name your plugins / source codes like so:

msXXXExport.bas
msXXXImport.bas
msXXXTool.bas
...

Joshy

[D.J.Peters]

Here are an overview of the milkshape 3d model structure.

Joshy

click to enlarge: