The library toolbox

Two kinds of toolbox

Runtime built-ins such as Rgb(), Key_Held(), and Draw Text are part of the language. Libraries are reusable SMILE code you add to a project and access with Import. A package can contain several modules; each module has a focused job.

The current compiler identifies Smile.Game, Smile.UI, and Smile.RPG as built-in libraries. The same repository also maintains the 3D and teaching packages below. They still need an explicit project or package reference.

Add a library in two steps

1. In Visual Studio, use your project's References → Add SMILE 2.0 Library Reference… to select a .smilelibproj project or a built .smilelib package.
2. Import the module you want in each source file that uses it. The alias after As is the short name you write in code.

Option Explicit
Import Smile.Game.Collision2D As Collision

Print Collision.CellsOverlap(3, 4, 3, 4)

This prints True: both positions occupy the same cell. Import names a module; it does not download a package or add a missing reference. Library dependencies must also be supplied at the required version.

The package map

Versions below are read from the current library project files. Start with the first three rows for 2D games; move into Simple3D when you are comfortable with the game loop.

Smile.Game: move one tile smoothly

CardinalMover separates the hero's logical cell from its animated pixel position. The destination becomes the real cell only when the move completes. Your game checks walls or occupied cells before starting a move.

Option Explicit

Import Smile.Game.Core As GCore
Import Smile.Game.Camera2D As Cameras
Import Smile.Game.Collision2D As Collision

Dim Hero As GCore.CardinalMover
Dim View As Cameras.CameraState
Dim Accepted As Boolean
Dim Arrived As Boolean
Dim StepIndex As Number

Call Hero.Place(2, 3, GCore.CardinalDirection.Right)
Accepted = View.Configure(320, 180, 1280, 720)

If Not Collision.OutsideMap(3, 3, 40, 22) Then
    Accepted = Hero.BeginMove(GCore.CardinalDirection.Right, 8)
End If

For StepIndex = 1 To 8
    Arrived = Hero.UpdateMove(1)
    Call View.Follow(Hero.VisualX(32), Hero.VisualY(32))
    Print Hero.VisualX(32)
End For

Print "Arrived: "; Arrived
Print "Cell: "; Hero.CellX; ", "; Hero.CellY
End Program

Download the movement example. Add the Smile.Game reference before building. Its printed X positions move from cell 2 toward cell 3; after eight steps, Arrived is True and the cell is 3, 3.

Animation and tile maps

Smile.Game.Animation keeps frame timing; you still draw the selected source rectangle. It supports 64 definitions with up to 16 frames each. Smile.Game.TileMap loads the documented SMILE-MAP 1 format, stores up to four maps, and draws Ground, Detail, and Foreground layers.

Import Smile.Game.Animation As Animation

Dim Walk As Number
Dim Accepted As Boolean
Dim FrameIndex As Number

Walk = Animation.Create(6, True, 0, 0)
If Animation.IsValid(Walk) Then
    Accepted = Animation.AddFrame(Walk, 0, 0, 32, 32)
    Accepted = Animation.AddFrame(Walk, 32, 0, 32, 32)
    FrameIndex = Animation.CurrentFrame(Walk, 7)
    Print FrameIndex
    Call Animation.Destroy(Walk)
End If

Here each frame lasts six caller-supplied steps. Seven elapsed steps select the second frame. The animation module does not read the clock for you. TileMap loading is transactional: an invalid load does not expose half a map.

Smile.UI: give the player a button

The Controls module is the smallest starting point. It detects clicks and draws controls; your game owns the meaning of a click.

Option Explicit

Import Smile.UI.Controls As Controls

Dim Selected As Boolean
Dim Key As Number

Game Window "My First Library Button" Size 640 By 360

Do
    Get Key Key
    If Controls.Clicked(220, 140, 200, 64) Then
        Selected = Not Selected
    End If

    Clear Rgb(12, 18, 36)
    Call Controls.DrawButton(220, 140, 200, 64, "Click Me", Selected)
    Draw Text "A library handles the button. You choose its action." At 320, 245 Size 16 Color WHITE Centered
    Show Screen
    Wait 16 Milliseconds

Loop Until Game_Closed() Or Key = KEY_ESCAPE

End Program

Download the button example. Add a Smile.UI reference. Click the button to toggle its selected state; Escape exits.

Menus and dialogue are objects

For keyboard-driven menus, use Import Smile.UI.Menu As Menus. Construct New Menus.Menu(Style, X, Y, Width, Height), check its Valid property, add choices with AddItem(Label, UserValue), feed queued keys to Update(Key), and draw with Call Menu.Draw(). MenuNavigator is exported by that same Menu module and handles submenus.

Smile.UI.Dialogue provides the Dialogue class for paged, gradually revealed text. Styles are value Types in Smile.UI.Core; skins, fonts, images, and sounds belong to your application. Call Destroy() explicitly: dialogues and navigators first, then their menus, then owned graphics. Setting a Class variable to Nothing releases that reference; it does not replace the documented bounded-slot cleanup.

See exact Menu, MenuNavigator, Dialogue, text, and font signatures.

Smile.RPG: rules and saved progress

A state handle holds one RPG session. Define stable character/item IDs before using them and register definitions before loading a save. The package calculates rules and progress; your game supplies pictures, input, and audio.

Option Explicit

Import Smile.RPG.Core As RPG
Import Smile.RPG.Party As Party

Dim State As Number
Dim Accepted As Boolean

State = RPG.Create()
If RPG.IsValid(State) Then
    Accepted = Party.AddGold(State, 25)
    Print "Gold: "; Party.Gold(State)
    Accepted = Party.SpendGold(State, 10)
    Print "Purchase accepted: "; Accepted
    Print "Gold left: "; Party.Gold(State)
    Call RPG.Destroy(State)
End If
End Program

Download the gold example. It prints 25 gold, a successful purchase, and 15 gold left. Always check Boolean/result-code returns before showing a success message.

Active battles are transient and are not serialized by SaveGames. Definitions and save-schema choices belong to your game.

Smile.Simple3D: step into an arena

Use Graphics3D for the introductory integer-world API, Precision3D for Double transforms, and ArenaViewport3D for the shared floor, grid, backdrop, and smooth camera controls. Character3D handles independent playback of shared character assets.

Create geometry once, update it each frame, open a 3D pass, draw, close that pass, then draw the ordinary 2D HUD and call Show Screen. Destroy owned resources when leaving the scene. True 3D requires a supported renderer; native GDI preserves the wireframe/2D fallback.

Build an arena and instantiate Fire, Water & Earth effects →

Battle presentation and time

Smile.Battle3D bridges RPG battle cues to actors, articulation, camera shots, and effects. It references Smile.RPG and Smile.Simple3D. Smile.BattleTime references Smile.RPG and exports Smile.RPG.BattleTime: Begin(StateHandle, Mode, Speed), Advance(StateHandle, Ticks, PresentationBusy), and TryStartRound(StateHandle) return Boolean results. Speed ranges from 1 to 5. Active mode advances while presentation is busy; Wait mode freezes it.

These are extensions for an existing battle system. Build your first moving character or small 2D game before adding battle orchestration.

Small packages for learning imports

Choose your next lesson

Draw, move, play sound, and save a score using runtime commands, or open the 55-function built-in reference when you need an exact signature.