3D Model Troubleshooting

If you've loaded 3D models into Aleph One, and your lighting or textures don't look quite right, this is the place for you. This page has advice on troubleshooting and correcting model problems. It assumes you've read through the <object> section of the MML Guide already; it's okay if not all of it made sense.

If you can't get your 3D model to show up at all in Aleph One, you need the Beginner's Tutorial, which unfortunately hasn't been written yet. One way to get started is to modify an existing 3D plugin from Simplici7y.

• MML settings: how to stay out of trouble before you start
• Coordinate systems: how to fix mirrored, rotated, or offset models
• Visibility and depth: how to fix disappearing or overlapping models
• Sides and normals: what's probably wrong when you don't know what's wrong

MML settings

Or, How to stay out of trouble before you start

For compatibility with old scenarios, Aleph One has a number of <model> parameters, some of which you should avoid for new projects.

• type - use a value of obj or max.
• scale - use a positive value, never a negative one.
• side and norm_type - leave these out unless you're sure you need them. (see Sides and normals)
• light_type - a value of 2 should look the nicest, especially for larger objects in dark areas. The default of 0 is fine for small models.

Outdated tutorials will tell you to flip your textures horizontally for use in Aleph One. This is never necessary if you follow the above advice.

Coordinate systems

Or, How to fix mirrored, rotated, or offset models

For OBJ files, Aleph One assumes a right-handed coordinate system with Y up:

• Positive Y is upward
• Positive Z is the direction the model is facing

For 3ds Max files, Aleph One assumes a right-handed coordinate system with Z up:

• Positive Z is upward
• Positive Y is the direction the model is facing

For both formats, the origin point (0, 0, 0) is the bottom center of the model. Units are in internal WU, where a value of 1024 is the size of one texture repeat. You can use the scale, shift, and rotation parameters in MML if it's awkward to adjust your modeling program's coordinates to match what Aleph One expects.

You may need to experiment with your modeling program's export settings for best results. For example, Blender's OBJ Export has a "Forward / Up Axis" setting to adjust the coordinate system. If you have a left-handed model, import and re-export it using a tool like Blender.

Visibility and depth

Or, How to fix disappearing or overlapping models

Aleph One's visibility and depth-sorting code is designed for 2D sprites, so it doesn't work so well with 3D models, but there are things you can do to lessen the problems.

Your 3D model will only show up when its corresponding map polygon is in view. If at all possible, avoid placing a model which extends into neighboring polygons, since players might catch those models disappearing or appearing. Earlier versions of Aleph One also required the model's center to be in front of the player; this was fixed in 1.2.

2D sprites in Aleph One are drawn without the depth buffer active, since depth clipping calls attention to the flat "billboard" nature of the sprites. If a 2D monster runs past your 3D model, it will by default appear either fully in front of or fully behind the model. You can control this with a few parameters in your <object> MML:

• depth_type will set the point at which other sprites swap from being in front of your model to being behind it. If you're noticing artifacts, try + for opaque models or - for translucent models.
• force_sprite_depth will turn on the depth buffer and cause sprites to be clipped as they pass through your model. This can look more realistic if your model has large holes (like an arch or tunnel), but the depth buffer will cause other artifacts, like cutting off half of an explosion against the floor. Use this option sparingly.

In general, the larger the model the more likely you will have depth-related problems. If you can, try to break up a large model into smaller pieces and place those individually.

Sides and normals

Or, What's probably wrong when you don't know what's wrong

If you can see through some of your model's polygons, try setting side="-" in your MML. By default, Aleph One assumes polygons should be visible from the side defined by clockwise vertices, but some models use counterclockwise instead. Some models use no convention: you can use side="0" to draw both sides, but you'll probably run into issues with normals (see below).

If you're having issues with lighting or bump maps, or you can see through your model only through certain angles, you might be having trouble with your model's normals. A normal is a vector associated with a vertex; these tell Aleph One which way the surface is pointing. Used properly, normals can make a low-res model look smoother and enable great lighting effects. Used improperly, a model will look too light or dark, or exhibit even stranger problems.

To check your model's normals, the Model Debugger plugin lets you visualize the normals as colors. (Color blind users should ask for assistance on the Pfhorums.) Model Debugger replaces all textures with a color based on which direction each 2D polygon is facing. If you look at the screenshot on that plugin page, notice that the floor is green, and the walls are blue or purple. The SMG models have similar colors: the top is green because it's facing the ceiling, and the vertical sides are blue or purple. The ammo box is totally different, though: the sides are shades of red instead of blue. This means the ammo box normals are wrong.

Once you know this is the problem, how do you fix it?

1. Make sure you aren't using dodgy MML settings. For instance, don't use <model type="wave"> to load your file.

2. Export models with the right coordinate system. Consult your modeling program's documentation to make sure you are exporting a right-handed model. If you're not sure, try making a non-symmetric model and see if it loads correctly in Aleph One.

3. Tell Aleph One which sides are visible, with side="+" or side="-". This helps with the next step.

4. Tell Aleph One to calculate the normals from scratch, ignoring any originally set in the model. Use norm_type="3" if your model has clockwise sides (side="+"), or norm_type="4" if your model has counterclockwise sides.