BGE/Parsers
Alias: BGE.Parsers
Static Methods
parseOBJFile(filePath: string): BGE.Model3d
Loads and parses a Wavefront .obj file's geometry, plus its texture if the file references one via mtllib/map_Kd (see parseOBJContent's doc comment).
Parameters
filePath(string)
Returns
parseOBJContent(content: string, baseDir?: string): BGE.Model3d
Parses the geometry of a Wavefront .obj file's content: v vertices, vt texture coordinates, and f faces, fan-triangulating any face with more than 3 vertices (a quad or n-gon). vn indices in a face line are read only far enough to skip over them correctly - per-vertex normals aren't retained, since Model3dFace only supports one flat normal per face; every face's normal is instead computed from its own vertex geometry (Model3dFaceOps.create()'s default when no normal is given), the same as an STL face with a missing/zero normal.
vt UV coordinates ARE retained now (issue #89): a face where every corner has a vt index (v/vt or v/vt/vn) gets a Model3dFace.Texture with normalized (0..1) UV points; a face where any corner lacks one (v//vn or bare v) gets no Texture at all, falling back to flat-color rendering for that face only.
usemtl sets the material of the faces after it (Model3dFace.material). mtllib <name>.mtl (first occurrence only, matching this parser's o/g handling) is resolved relative to baseDir and read from disk: its materials become the model's materials (each map_Kd resolved relative to the .mtl's folder), and its first map_Kd the model's texturePath, used by faces with no material - only when baseDir is given (parseOBJFile always supplies it; a bare parseOBJContent(content) call, e.g. from a unit test with no real file on disk, skips mtllib resolution entirely and just parses geometry).
Parameters
content(string) — the raw text content of a .obj filebaseDir(string, optional, default: "\"\"") — the directory the .obj file lives in, for resolving mtllib/map_Kd paths; "" skips that resolution entirely
Returns
resolveOBJFaceVertices(
faceTokens: Array.<string>,
vertices: Array.<BGE.Math.Vector>,
): Array.<BGE.Math.Vector>
Resolves a face line's v/v/vt/v//vn/v/vt/vn tokens (tokens[1..]) to the actual vertex positions they reference.
Parameters
faceTokens(Array.<string>) — the full tokenized face line, including the leading "f"vertices(Array.<BGE.Math.Vector>) — every vertex parsed so far
Returns
Array.<BGE.Math.Vector>
resolveOBJFaceTexCoords(
faceTokens: Array.<string>,
texCoords: Array.<BGE.Math.Vector>,
): Array.<BGE.Math.Vector>
Resolves a face line's per-corner vt index (the 2nd /-separated part of each v/vt/v/vt/vn token) to the actual UV points they reference. Returns an EMPTY array the moment any corner is missing a vt index or an already-parsed texCoord
- callers compare the returned array's length against the vertex count to know whether every corner resolved.
Parameters
faceTokens(Array.<string>) — the full tokenized face line, including the leading "f"texCoords(Array.<BGE.Math.Vector>) — every vt UV point parsed so far
Returns
Array.<BGE.Math.Vector>
appendOBJFace(
faces: Array.<BGE.Model3dFace>,
faceVertices: Array.<BGE.Math.Vector>,
faceTexCoords: Array.<BGE.Math.Vector>,
material?: string,
): void
Fan-triangulates a face's already-resolved vertices (3 for a plain triangle, more for a quad/n-gon) and appends the resulting triangle(s) to faces. faceTexCoords is fanned the same way when it has one UV point per vertex (i.e. every corner resolved a vt - see resolveOBJFaceTexCoords) - otherwise no triangle from this face gets a Texture.
Parameters
faces(Array.<BGE.Model3dFace>)faceVertices(Array.<BGE.Math.Vector>)faceTexCoords(Array.<BGE.Math.Vector>)material(string, optional, default: "\"\"") — the material (usemtl) in effect for this face, "" for none
Returns
void
resolveOBJIndex(indexStr: string, count: integer): integer
Resolves a single (1-based, or negative/relative per the .obj spec) OBJ index string to a 0-based index into an array of the given count.
Parameters
indexStr(string)count(integer) — the current length of the array this index is into
Returns
integer
resolveOBJMaterials(
baseDir: string,
mtllibName: string,
): Array.<BGE.Model3dMaterial>
Reads baseDir/mtllibName from disk and returns its materials, with each map_Kd resolved against the .mtl file's own folder. Empty if the file can't be read.
Parameters
baseDir(string) — the .obj file's own directorymtllibName(string) — the mtllib line's filename, as written in the .obj
Returns
Array.<BGE.Model3dMaterial>— in the order the .mtl defines them
setOBJMaterials(
model: BGE.Model3d,
materials: Array.<BGE.Model3dMaterial>,
): void
Sets a model's materials, by name, and its texturePath to the first material's texture (used by faces with no material).
Parameters
model(BGE.Model3d)materials(Array.<BGE.Model3dMaterial>) — in the order the .mtl defines them
Returns
void
parseMTLContent(mtlContent: string): Array.<BGE.Model3dMaterial>
Parses a .mtl file's materials: each newmtl block's name, map_Kd texture (as written, not resolved) and Kd diffuse color. Other properties are ignored.
Parameters
mtlContent(string) — the raw text content of a .mtl file
Returns
Array.<BGE.Model3dMaterial>— in the order the file defines them
mtlColorToRGBA(r: string, g: string, b: string): integer
Converts a .mtl color's 0..1 red, green and blue to packed RGBA (opaque).
Parameters
r(string)g(string)b(string)
Returns
integer
splitOBJLine(rawLine: string): Array.<string>
Splits an .obj or .mtl line into its space- or tab-separated tokens.
Parameters
rawLine(string)
Returns
Array.<string>
joinOBJTokens(tokens: Array.<string>, start: integer): string
Joins a line's tokens from start on with single spaces - a name or filename that contains spaces.
Parameters
tokens(Array.<string>)start(integer)
Returns
string
getMTLMapFileName(tokens: Array.<string>): string
The filename in a .mtl texture line (e.g. map_Kd -s 1 1 1 my texture.png): the tokens after the keyword and any option flags (-name and its values).
Parameters
tokens(Array.<string>) — the line's tokens, the keyword first
Returns
string
isMTLOptionValue(token: string): boolean
Whether a .mtl option token is a value (a number, or on/off) rather than a filename.
Parameters
token(string)
Returns
boolean
joinObjPath(baseDir: string, relativePath: string): string
Joins a base directory and a relative path, regardless of whether baseDir already ends with a "/".
Parameters
baseDir(string)relativePath(string)
Returns
string
parseSTLFile(filePath: string): BGE.Model3d
Parameters
filePath(string)
Returns
parseSTLAsciiFile(content: string): BGE.Model3d
Parameters
content(string)
Returns
parseSTLBinaryFile(fileBytes: roByteArray): BGE.Model3d
Parameters
fileBytes(roByteArray)
Returns
stlStringToFloat(input: string): float
Parameters
input(string)
Returns
float
Other
ModelParseTask
Extends: BGE.LoadTask
Base class for the step-by-step model parsers (OBJParseTask, STLAsciiParseTask, STLBinaryParseTask). model is set once step() returns true, and stays invalid if the content couldn't be parsed.
Properties
model(BGE.Model3d) — The parsed model, once done
OBJParseTask
Extends: ModelParseTask
Parses Wavefront .obj content a slice at a time - see BGE.AssetLoader.load3dModel(). model is set once step() returns true. Same results as parseOBJContent(), which runs one of these to completion.
Parameters
content(string)baseDir(string, optional, default: "\"\"")
Properties
mtllibName(string) — The material library the file names (mtllib), or "" - set while parsing
Returns
BGE.Parsers.OBJParseTask
STLAsciiParseTask
Extends: ModelParseTask
Parses ASCII .stl content a slice at a time. model is set once step() returns true (invalid if the content couldn't be parsed). Same results as parseSTLAsciiFile().
Parameters
content(string)
Returns
BGE.Parsers.STLAsciiParseTask
STLBinaryParseTask
Extends: ModelParseTask
Parses binary .stl bytes a slice of triangles at a time. Same results as parseSTLBinaryFile().
Parameters
fileBytes(roByteArray)
Returns
BGE.Parsers.STLBinaryParseTask