Back to main page

Debug guide

If a model that you need to debug is generated in the game, save the result to a file using Model_SaveToFile_InSB and open it in the model editor.

The application is crashing when closing the main window!

Terminate the application when the window class is unloading. Both rendering and the sound engine is using the window and will get a nasty surprise if it suddenly does not exist.

The application is crashing when giving multiple calls at once to the engine!

Only make one call at a time and treat the whole engine as shared variable.

The application is crashing without closing the window or using multiple threads!

Download and use the latest version of the engine or send a bug report about the error. Send a link to a small project with sourcecode that recreate the error.

The image is black!

If you have disabled automatic swap chain using Engine_SetAutomaticSwapChain, you must call Engine_UpdateSwapChain to show the final draw surface to the user.

My shader animation is not moving!

Use Shader_SetGlobalTime before each render to give the current time to all your shaders.

I can't change the shader for one of my models!

Note that a model can have multiple parts with different sets of shaders.

Alpha filtering is not working!

Make sure that your texture's alpha channel was loaded by using an HLSL shader that show alpha as grayscale.

Make sure that your shader is returning the alpha channel to the render target by using a post effect that show alpha as grayscale.

Make sure that the model is using alpha filter by opening it in the model editor.

Make sure that you are rendering the same shader channel that the shader is assigned to.

My soft particles are not working at all!

See "Alpha filtering is not working" since soft particles only work with filters.

Make sure that the draw surface that the scene is rendered to is using 2 depth buffers.

My soft particles look flat when intersecting solid geometry!

Use this:

// This value represent the solid background's camera space Z depth and is generated by sampling the depth buffer copy and converting from ZW to linear using the current camera's projection matrix.

float DepthBufferLinear = CameraToImage._43 / (tex_depthBufferCopy.Sample( samConstant, input.Pos.xy / Dimensions ) - CameraToImage._33);

// This value can be multiplied with the final alpha.

float CloseToBackgroundFading = saturate(DepthBufferLinear - input.Pos_CameraSpace.z);

My soft particles look flat when intersecting the camera!

Use this:

// This value can be multiplied with the final alpha so that it fade away softly when being close to the near clip plane.

float CloseToCameraFading = saturate(input.Pos_CameraSpace.z - NearClipPlane);

Alpha clipping is not working!

Make sure that your texture's alpha channel was loaded by using an HLSL shader that show alpha as grayscale.

Clip the pixel when alpha is below 0.5 for a smooth edge.

Make sure that you are rendering the same shader channel that the shader is assigned to.

My item look strange!

Start by reading your shader code and compare it with working shaders.

Return a simple color from your shader to see that you are editing the same shader that you see.

Return one vertex property at a time from the shader to see that they are working.

Use the editor to make sure that the vertex color and texture coordinates are not 0.

Use the editor to generate normals if your shader is using them.

Make sure that all texture channels sampled by the material shader has an image assigned.

My item is not visible!

Make sure that the instance's axis system is well scaled.

Make sure that the instance is visible in the shader channel that your camera is rendering. Use Instance_GetVisibility and Instance_SetVisibility.

Make sure that the model is using the correct culling method. Use the model editor to choose a method. Try using no culling to make sure that you have found the error before choosing the right type.

Make sure that the model has visible parts in all detail levels. Try viewing the model in low, medium and high detail level in the model editor.

My item is not casting shadows!

Make sure that the light source is shadowcasting. The constructor method should include "_Shadowcasting" and not "_Shadowless"

Make sure that the light source has shadow transparency set to 0. Use LightSource_GetShadowTransparency and LightSource_SetShadowTransparency.

Make sure that the depth atlas is not out of space. Use Debug_WasDepthAtlasAllocationDenied before calling LightSource_ClearShadows.

Make sure that the instance is casting shadows. Use Instance_GetVisibility and Instance_SetVisibility with shader channel 1.

Make sure that all parts in the model have a shader in channel 1 (depth only). Use the model editor.

Make sure that the depth only shader is not clipping everything from a bad vertex color or bad HLSL code. Use the model editor to see what shaders are assigned to channel 1.

My shadowcasting light source is casting weird shadows and I use one camera/render call!

Call LightSource_ClearShadows before each render to remove the first thing that the light source saw.

My shadowcasting light source is casting weird shadows and I use multiple cameras/render calls!

Call LightSource_ClearShadows before the frame's first render so that the first render call that show the light source will render the depth map and the next render calls will reuse that map. This looks as if the light source is projecting an image.

Make sure that light source is not moved in any way between the render calls. This bug took days to find in the forest example because it looks like an internal error.

Make sure that no shadowcasting instance is moved between the render calls.

My shadowcasting light sources take too much rendering time and I use multiple cameras/render calls!

Only call LightSource_ClearShadows before the frame's first render so that the next render calls will reuse that depth map that was created the first time the light source was visible.

I can't use my draw surface as a dynamic texture!

Make sure that the part's instance override is listening to the same channel that you assigned the draw surface to using Instance_SetTextureOverride.

Make sure that the used shader is sampling the texture channel that you are overriding.

I have generated a sound but I can't hear it.

Call Sound_Buffer_Editable_Update before playing it.

Try saving the current content to a wave file and opening the result in a sound editor to see if it is a sound or a flat line.

The visual instance is not following the rigid body when I place the instance at the rigid body manually.

Call Instance_PlaceAtRigidBody or Instance_PlaceAtRigidBody_Interpolated with the instance and rigid body before each render.

The visual instance is not following the rigid body when I let the instance follow the rigid body automatically.

Make sure that you have connected the instance to the rigid body using Instance_FollowRigidBody

Call Physics_LetInstancesFollowRigidBodies or Physics_LetInstancesFollowRigidBodies_Interpolated before each render.

The visual instance is not scaled like the rigid body's shape.

Make sure that the UseLocalScaling flag is true in the method that you use to synchronize the instance with the rigid body.

Make sure that the shape is scaled using the local scaling property and not just using different dimensions when creating the shape. You should think of the shape's dimensions as object space and local scaling as the conversion to world space.