3D Graphics

RCBasic includes a full 3D rendering and physics pipeline. This section gives a practical introduction to the core concepts.

Opening a 3D Canvas

Render the 3D scene with a canvas opened via OpenCanvas3D():

scene_canvas = OpenCanvas3D(0, 0, 640, 480, 1)

Each 3D canvas has its own camera. You can open multiple 3D canvases to display the scene from different angles, but each additional canvas re-renders the full scene so use them sparingly.

Note

2D drawing commands do not work on 3D canvases. Open a separate 2D canvas for overlaid UI or HUD elements.

Actors

Actors are objects in the 3D scene — the 3D equivalent of sprites. Different actor types serve different purposes (animated characters, static geometry, lights, terrain, vehicles, …).

Creating an animated actor:

  hero_mesh = LoadMesh("char.ms3d")         ' load the 3D model once
hero      = CreateAnimatedActor(hero_mesh) ' create a scene object from it

Adding Animation

  ' CreateActorAnimation(actor, start_frame, end_frame, speed_fps)
RUN_ANIMATION = CreateActorAnimation(hero, 13, 36, 30)

' Play animation; -1 = loop forever
SetActorAnimation(hero, RUN_ANIMATION, -1)

Applying a Texture

Actors start without colour. Get the actor’s material, disable lighting if you want unlit rendering, load a texture, and apply it:

  hero_material = GetActorMaterial(hero, 0)
SetMaterialLighting(hero_material, FALSE)

hero_texture = LoadImage("hero.png")
SetMaterialTexture(hero_material, 0, hero_texture)

3D Physics

  SetActorSolid(hero, TRUE)
SetGravity3D(0, -10, 0)    ' gravity pulls in -Y direction

Ground plane

Create a plane mesh and an octree actor (optimised for large static meshes):

  plane_mesh = CreatePlaneMesh(1000, 1000, 100, 100, 100, 100)
plane      = CreateOctreeActor(plane_mesh)

' Solid colour material
plane_material = CreateMaterial()
SetMaterialType(plane_material, FX_MATERIAL_TYPE_PLASTIC)
SetActorMaterial(plane, 0, plane_material)

SetActorSolid(plane, TRUE)
SetActorShape(plane, ACTOR_SHAPE_TRIMESH, 0)

Moving an Actor with Keyboard Input

  If Key(K_RIGHT) Then
    SetActorLinearVelocityLocal(hero, 0, 0, 20)
End If

Local vs World transforms

Type	Behaviour
Local	Relative to the actor’s own orientation. Moving along +Z moves the actor forward (the direction it faces).
World	Relative to the global axes. Moving along +Z always moves in the world’s +Z direction regardless of the actor’s rotation.

Camera Setup

Each 3D canvas has its own camera. Activate the canvas first, then call the camera functions:

  Canvas(scene_canvas)

SetCameraPosition(0, 30, -100)   ' position in world space
SetCameraRotation(20, 0, 0)      ' pitch 20° downward

Additional camera settings: FOV, aspect ratio, near/far clip planes — see Camera.

Complete Skeleton

  OpenWindow("3D Demo", 640, 480, false, true)

scene_canvas = OpenCanvas3D(0, 0, 640, 480, 1)
Canvas(scene_canvas)

SetCameraPosition(0, 30, -100)
SetCameraRotation(20, 0, 0)
SetGravity3D(0, -10, 0)

hero_mesh = LoadMesh("char.ms3d")
hero      = CreateAnimatedActor(hero_mesh)

mat = GetActorMaterial(hero, 0)
SetMaterialLighting(mat, FALSE)
SetMaterialTexture(mat, 0, LoadImage("hero.png"))

RUN = CreateActorAnimation(hero, 13, 36, 30)
SetActorAnimation(hero, RUN, -1)
SetActorSolid(hero, TRUE)

plane      = CreateOctreeActor(CreatePlaneMesh(1000, 1000, 100, 100, 100, 100))
plane_mat  = CreateMaterial()
SetMaterialType(plane_mat, FX_MATERIAL_TYPE_PLASTIC)
SetActorMaterial(plane, 0, plane_mat)
SetActorSolid(plane, TRUE)
SetActorShape(plane, ACTOR_SHAPE_TRIMESH, 0)

While NOT Key(K_ESCAPE)
    If Key(K_RIGHT) Then
        SetActorLinearVelocityLocal(hero, 0, 0, 20)
    End If
    Update()
Wend