1. BLITZ3D INTRO
I learned Blitz3D by studying the built in SAMPLES (they were heavily commented with helpful explanations) , 3D tutorials, Command Reference, and especially the official Blitz3D forums, code archives and toolbox! For beginners though this is NOT the easiest way to learn. I first learned BASIC on a TRS-80 Model II back in the early 80's. The manual that came with it had lots of exciting game examples, explained things simply, and introduced new commands only when absolutely necessary. This is what I am attempting to recreate for you here. So, get ready for an exciting adventure in coding a real 3D game that will be FUN & ADDICTING!
Which way is UP?!
Unlike the standard XY coordinate system of 2D games where the upper left corner of the screen is (0,0) , the 3D game world positions the XY axes on the CENTER of the screen. The Z-direction is oriented as forward (+) and backward (-). This can be confusing to 2D coders since Z is typically verticke UP & DOWN. When you place or move an object in your 3D world it is easy to see this XYZ relationship, BUT once you start moving a CAMERA things can get disorienting pretty quickly.

Placing an object in 3D space has more variety than just an x,y,z position.
You can also TURN any object (even the camera!) about each of the X, Y & Z axes. Turning about the X is called PITCH, Y is YAW and Z is ROLL, just like if you were flying an airplane (see diagram). These turns are measured in degrees (0-360). Don't worry though if you forget, once you run your game and see something turn the wrong way you can just change the code and try it again until you get it right.


Let's Get Started!!! - - - The Game Skeleton
The following code represents the bare bones of a common 3D game. The yellow comments (start with a semi-colon) offer additional explanation and are ignored by Blitz. Commenting your code is a professional practice and will save you hours of frustration down the road. If you remove all the comments you can appreciate how little code is actually required to get a simple 3D game up and going!

If you haven't already downloaded the tutorial files do so now, unzip to your desktop and OPEN up lesson1.bb (below) and RUN / LAUNCH the lesson1.bb program by pressing the ROCKET ICON

and you should see this...


Here's the CODE!
lesson1.bb

; Insert future code HERE! i.e. constants, variables, functions

; Scancode for Escape Key is 1
; "Globalizing" is good for commonly used values

Global escape_key = 1
Global screen_width = 640, screen_height = 480


; Set video mode
Graphics3D screen_width, screen_height, 16, 2
SetBuffer BackBuffer()

; Setup camera
cam1 = CreateCamera()
CameraViewport cam1, 0, 0, screen_width, screen_height


; Load level objects, e.g. trees, rocks, enemies, lights, etc
light1 = CreateLight( 2 ) ; 2 = Point Light Type
cube1 = CreateCube()
PositionEntity cube1 ,-2, -2, 10

; The MAIN GAME LOOP Keeps repeating While you do NOT press ESCape

While Not KeyHit( escape_key )
     ; Keyboard & Mouse Controls will be here
     ; 3D Object Changes Go Here, e.g. move/animate objects, shoot, check collisions...


     UpdateWorld
     RenderWorld

     ; 2D stuff here, update HUD, text, stats...
     Text 50,50,"Hello Cube!"

     Flip
Wend

End

; Repeatedly used functions appear here later


NEW COMMANDS
Global escape_key = 1
Global screen_width = 640, screen_height = 480


Graphics3D screen_width, screen_height, 16, 2
The scancode for the ESCape key happens to be 1 so we are storing it's value in a Global variable with the helpful name "escape_key".
Graphics3D screen_width, screen_height, 16, 2
sets the 3D graphics card so the game screen has a size of 640 x 480 pixels using 16 bit color within a windowed frame (1=full screen, 2=windowed). You will find that running fullscreen can speed up your game significantly in many cases.
EXPERIMENT !
Change escape_key = 1 to escape_key = 28

Now you have to press the ENTER key to stop your program!


Change Global screen_width = 640, screen_height = 480

to Global screen_width = 320, screen_height = 240

What's different?

Change Graphics3D screen_width, screen_height, 16, 2
to Graphics3D screen_width, screen_height, 16, 1

Time for FULLSCREEN!
Undo the changes you made...

SetBuffer BackBuffer() . . . goes with Flip
Sounds pretty geeky huh? Using SetBuffer BackBuffer() is a technique in animation where you draw your world objects to a hidden back page (aka Backbuffer) while the frontpage is being shown. Once the 3D objects have been moved and then "painted" to the hidden BackBuffer area, the FLIP command switches the BackBuffer to the FrontBuffer. This prevents an annoying problem known as screen flicker and creates smoother animated worlds.

light1 = CreateLight( 2 )
cam1 = CreateCamera()
CameraViewport cam1, 0, 0, screen_width, screen_height
light1 = CreateLight( 2 ) creates a standard point light named light1. (1 = directional (default) , 2 = point, 3 = spot )

cam1 = CreateCamera()
creates a camera named cam1. You can control where this camera points in your world with the keyboard or mouse (covered later). You can even attach (called "Parenting") the camera to other objects to make a 1st or 3rd person view.
CameraViewport cam1, 0, 0, screen_width, screen_height
sets up the portion of the screen that will display what cam1 "sees" (what is placed in front of it) and in this case it's the entire game screen. You can create multiple cameras for effects like split screen, rearview mirror, etc...

cube1=CreateCube()
PositionEntity cube1, -2, -2, 10
cube=CreateCube() simply creates a cube in your world centered at 0,0,0 with opposite corners reaching from -1,-1,-1 to +1,+1,+1. This primitive shape entity can be Scaled, Positioned, Rotated, Colored, Textured and Alpha (transparency) adjusted to suit a wide variety of world building purposes. e.g. EntityColor cube1, 255,0,0 will color the cube red. Other primitive entities you can create are Planes, Spheres, Cylinders and Cones. You can also add the number 16 or 32 in the parenthesis if you want a higher segmented (smoother) looking shape, e.g. CreateSphere(16).
EXPERIMENT !
After cube1=CreateCube()
ADD
texture1 = LoadTexture("water.jpg")
EntityTexture cube1, texture1

Cool huh?! Try adding your own 256 x 256 graphic in the folder and applying it to an object!

After PositionEntity cube1, -2, -2, 10
ADD
cone1=CreateCone()
PositionEntity cone1, 4, -2, 10


Try CreateSphere(), CreatePlane(), CreateCylinder()

After PositionEntity cone1, 4, -2, 10
ADD
EntityColor cone1, 255, 0, 0
EntityAlpha cone1, .2
RotateEntity cone1, 0, 0, 90

ScaleEntity cone1, .5, 2, .5

Now what happened?!
The cone changed red, became see thru, rotated and got long and skinny!
Most paint programs will give you the 3 "RGB" numbers for any color shade you like!
The Alpha "Transparency" can vary between 0 (Invisible) and 1 (Solid)
Rotations on any of the X,Y, and Z axis can vary from 0 to 360 degrees
Scale can range from .001 up to 1000+

While Not KeyHit( escape_key ) , goes with Wend
This begins our MAIN GAME LOOP and checks to see if the Escape Key (scancode = 1) has NOT been pressed KeyHIT( ). If it has, the game drops out of the loop and Ends. Check out available scancodes HERE .

The game loop consists of checking for additional key or mouse input from the user, giving each object a bit of time to be moved a bit (player, enemies, projectiles) , checking for collisions, updating stats, and displaying the HUD GUI (Heads Up Display Graphical User Interface) e.g. score, life, mana, power, radar, etc.


3D objects must be adjusted first, followed by the 2D elements since whatever is drawn last can overwrite on top of what was drawn before. Wend designates the end of the While loop.

  UpdateWorld
  RenderWorld
UpdateWorld updates the objects that we may have previously moved, scaled, rotated, etc. plus dealing with any collisions we might set up later.  
RenderWorld
graphically renders the objects/scene to the BackBuffer() (hidden page) awaiting the FLIP command to actually display to the screen.

  Text 50,50,"Hello Cube"
  Flip
Wend

End
After RenderWorld we can now place our 2D elemenets, e.g. score, life, mana, power, radar, etc.
Text 50,50,"Hello Cube"
places the words "Hello Cube" at X,Y game screen location 50,50 measured from the upper left corner. Text/Sprites/Images are placed/updated here before the FLIP command that then brings our hidden page (with BOTH 3D and 2D elements) to the screen. Wend sends us back to the start of the game loop for the next update of all our world object changes all over again.
EXPERIMENT !
Change Text 50,50,"Hello Cube"
to Text 50,50,"Something Else "


THE CHALLENGE!!!
Create a scene with several different primitives repositioned, scaled, and textured to make a whole new world.

NEXT : Lesson 2 - CONTROL