One of the most frustrating things is when you can't see or find your object in your world. There are many, many possible reasons for an object not appearing properly.

Here are some general categories of problems (I treat these in more detail below):

• The world was not created properly
• The object was not created properly
• The object was not added to the world (or was added as a child to something that isn't in the world).
• The object was previously added to the world but has been removed (unlikely unless you've intentionally removed it)

• The object is in the world but your camera can't see it.
• The object is in the world but is invisible for some other reason.

In all cases, the key is to start with a simple example, such as Petit's tutorial, and build up the functionality in incremental stages, verifying at each point. If your example previously worked and suddenly stopped working, the obvious culprit is your most recent change. Undo your recent changes (hopefully you've kept a backup of a recent stable version) and see if you can get back to a known working state.

Debugging is the systematic challenging on one's assumptions. So verify each step, and each sub-step of each step, until you find the problem. Sandy is open source, so you can usually examine exactly the code you need to find the problem, which may be in the Sandy library itself, especially when using a beta version. When in doubt, ask for help in the forum (after reading this FAQ of course).

The first task it to create your world and add a camera and root group to it. If you've done that properly and also added at least one visible object to your root group, you should be able to see something in your world.

There are many ActionScript-related issues, having nothing directly to do with Sandy, that can conspire against you. The most common problems are scope-related and having the wrong classPath. This FAQ doesn't address syntax checking or problems getting your code to compile. It assumes that your code compiles without errors but that it fails to perform as desired.

You should always use ActionScript classes for all your Sandy-related code. Compiling classes in the Flash 8 authoring tool will give you lots of syntax checking to help diagnose and avoid problems in your code. For example, if you haven't imported the TextureSkin class, and you're writing timeline-based code, Flash won't warn you of the problem. If however, you attempt to create a TextureSkin in a class that doesn't import the TextureSkin class, Flash 8 will issue a warning when you try to compile. That is all I'm going to say about general ActionScript tips here. There are many more ways to improve your code including meticulous error-checking, typing all your variables, using unit tests, etc., but these are beyond the scope of this FAQ.

Later, I'll add examples of creating a world in 1.1 and 1.2. See Petit's tutorial for Sandy 1.1 code. For 1.2, see the FAQ on changes between the two versions (basically, for 1.2, you must change your Camera3D constructor and use World3D.setCamera() instead of World3D.addCamera()).

To create your world, make sure you've done the following

• Import the correct classes from the correct classPath
• Create a camera with the Camera3D class (see Camera tips below)
• Position the camera in the world and look at the right location
• Add the camera to the world.
• Create a group and set it as the root group for the world.
• Add a known working test object, such as a primitive with a SimpleLineSkin to the world.
• Render the world.

(Code examples to be added in the future…)

If your world was created properly, your initial test object should appear. However, this is a bit of a chicken-and-egg problem. You can't tell if your world was created properly unless you see some object in it. And if the object doesn't appear, you don't know if it is because the object creation was bad or it was put into a non-existent world.

Your initial goal should be to render one object, any object, at any visible location so that you know your world exists and objects can be placed in it. Then you can work on the details of your other problems.

Start with Petit's tutorials and create a known primitive object, such as a Box or Pyramid. Be sure you've set all the constructor parameters correctly for the version of Sandy you are using. If you cannot get his tutorial working (or something similar) keep going back to the simplest possible case (i.e., creating a world with one object in it).

That said, if you can't get one object visible, then you don't know if any object is visible. So always go back to a known example. Petit draws axes in the world, which act as a great reference point.

Remember, your object may be created properly but not be placed in the world properly and may be invisible for other reasons. (see below)

Even if your object was created properly, it won't appear until it is added to the world.

If you've successfully created your world, especially if you can view other objects, then your object may not have been added properly.

Try adding it to the rootgroup with addChild().

If you are adding it as a child of another group, again see Petit's tutorials about how to add something to a transform group. Start with default positions and rotations, such as (0,0,0). If you can get it to appear there, then you can move it later.

Seeing your world is dependent on three things:

• The world existing with objects in it.
• Those objects being rendered in a visible way.
• Your camera showing you the portion of interest of your world.

It is exceedingly common for a problem to be related to your camera either not existing or not looking at the right place.

Therefore, you should check:

• Has your camera been created properly (with new Camera3D()) and have you passed the correct parameters to the constructor?
• Has the camera been added to the world with addCamera() in Sandy 1.1 or setCamera() in Sandy 1.2?
• You must use Camera3D.translate to move the camera to a negative z position. By default, the camera is at the origin and can't see things placed there; so you need to back it off to a negative z position, such as by using cam.translate(0,0,-100);
• Is your camera looking at the right place? It may be pointing in the wrong direction. Try using cam.lookAt(0,0,0); to reset it to look at the origin of your world (but not if you are trying, say, to tilt the camera, as using lookAt(0,0,0) will cancel certain other camera movements).
• Is your camera ridiculously far away from the object you want to look at? It is possible that objects are so small as to be invisible because the camera was zoomed out to a huge distance (either by position or focal distance). So change the camera's position or focal length.
• Is the object of interest behind your camera or off too far to the side? If so, your camera won't see it. Again, make sure an object exists at the origin and point your camera there.
• Are you too close to the object? Some things won't render if you are too close to them or if they are outside your viewing angle, so zoom out a little bit to get a broader view of the world.
• Is your camera looking straight at your world from an angle at which z is zero? Do not set the z position to 0 or your scene may disappear. Set it to 1, such as cam.translate(0,500,1), not cam.translate(0,500,0) This is a known limitation when vectors align. I think it is kludged for you in Sandy 1.2, but in Sandy 1.1, setting the camera to (0, 500, 0) or similar, will make the scene disappear.
• Your camera is seeing an invisible portion of an object, such as its back or inside (see below).
• If using Sandy 1.2 or later, are your near and far planes wrong? The near plane must be at a positive distance that is less than the far plane. The far plane must be at a positive distance that is greater than the near plane.
• Is it a clipping problem in which that part of the world is thought to be outside the viewport area? (add some info about enabling/disabling clipping)

Assuming your world is created properly and your camera is looking at the right place, you still need to put some object in the world at the right location. Assuming you can see at least one object in the world, here are some other reasons a given object might not appear.

The most common problem causing an object that would otherwise be visible to be invisible is its skinning. Be sure to import the necessary skinning classes.

To work out the skinning of an object:

• Begin with the default skin. Use setSkin() to set a SimpleColorSkin or SimpleLineSkin. Then try a MixedSkin.
• If using a MovieSkin, you must use Flash 8 or later, not Flash 7. The MovieSkin must point to an existing movie clip symbol in your library, I think, not a movie clip instance on stage. Basic Flash knowledge is required here.
• If using a TextureSkin, again, you must use Flash 8 or later. The TextureSkin must point to value bitmap data. This is especially tricky if loading external bitmaps, a topic not covered here.
• If using external textures or movie clips, there are many potential pitfalls including the fact that the content may not be loaded. You need to use an asynchronous callback, again not covered in the scope of this FAQ.

By default, the back or inside of an object isn't rendered. So if you rotate a plane away from the camera, it will seem to disappear. Likewise, if you put the camera inside a cube, it will seem to disappear.

To view the backfaces:

• Set enableBackfaceCulling to false.
• Use setBackSkin() to set a skin for the back, or leave it to the default.
• Use swapCulling() to render the inside or back of a surface.

There are many other reasons an object might not appear:

• Is the alpha (transparency) for the skin 0? Use alpha 100 with the skins discussed above until you get it working.
• Is the object at a valid location, such as 0,0,0?
• Is the object too far way from the camera?
• Is the width, height, or scale of the object very small? (See getBoundingBox(), I suppose?)
• Is something else blocking your object? You might have to temporarily delete or remove other objects to see the one of interest.

If an existing object disappears, it is, by definition, because something else changed.

Check the following

• Did you change the skin to something that made it fail, such as a MovieSkin? Try a different skin. I've had problems with MovieSkins in Sandy 1.2.
• Did changing the position cause it to disappear? Try moving it to a known location.
• Did you remove it manually in your code, even if that was accidental?
• Did you remove a parent group or object to which it belonged?
• Did you set its alpha to 0? Use an alpha of 100 with your skins until you debug it.
• Did you move the camera and forget to make it look at the object using cam.lookAt()?
• Did you remember to refresh the view? Use cam.rotateX(0) to refresh the world view.
• Did you change backface culling or the backskin in some way?
• What else changed?

There are many other potential pitfalls not discussed in detail here.

For example, if you are loading an external model, it is possible that:

• The model isn't loaded yet (loading is asynchronous and you need to use a callback).
• The model is too complex or in a format that Sandy can't understand.

Start with a simple primitive shape and work your way up to the more complex stuff.

Remember these keys:

• Separate the problem into what is known to be working and what is a potential culprit. You do this by simplifying your example and adding complexity in small increments, retesting at every point.
• Use basic debugging techniques to examine the state of variables (you can use trace() or the Flash debugger).
• Be meticulous in your error-checking.
• Scope, scope, scope! 90% of the ActionScript-related problems are due to scope issues.

It is often very helpful to use sliders to control the position of an object or a camera. This allows you to change the parameters at runtime to see their effects. See Petit's tutorials in this regard. But beware, the sliders themselves add a layer of complexity and potentially introduce errors if your code is incorrect.

When in doubt post to the help forums. See you there!

Cheers, Bruce (zeusprod)