`Console::API`

console 0.2.0 · app/console/core.rb · 760 lines · view source

Console -- the cartridge runtime.

This is the object a cart talks to. Console.boot is called once by app/main.rb, Console.tick runs 60x a second, and in between it owns:

draw      Console::Draw      rendering helpers
input     Console::Input     one action vocabulary
ui        Console::UI        widgets
entities  Console::EntityStore
anim      Console::Anim      animation state machines
audio     Console::Audio     sfx + music
camera    Console::Camera    world/screen transform
tweens    Console::TweenHost tweens, `after`, `every`
scenes    Console::SceneController

Frame order is fixed and worth knowing:

1. input snapshot          so a whole frame sees one consistent input state
2. timers / tickers / tweens
3. animations advance
4. scene update + scene draw   (or, with no scenes, cart update)
5. cart render (always last, so it is the place for a HUD)
6. HUD / warnings

scenes

def scene(name = nil, klass = nil, options = {}): scene :title, TitleScene register a scene scene :title go to a scene
def goto(name): line 352
def push_scene(name): line 356
def pop_scene: line 360
def unwind: line 364
def current_scene: line 368
def scene_depth: line 372
def scene_data(name = nil): Per-scene persistent state.

subsystems

def draw: line 383
def input: line 387
def ui: line 391
def entities: line 395
def anim: line 399
def audio: line 403
def camera: line 407
def tweens: line 411
def args: line 415
def screen: line 419

geometry

def rect(x, y, w, h): The handful of rect maths a cart actually reaches for. Anything more specific is Console::Geom, but these are the ones you would otherwise write by hand every time.
def center(r): The geometric centre of a rect.
def overlaps?(a, b, tolerance = 0.1): Do two rects overlap?
def inside?(r, x, y): Is a point inside a rect?
def percent(value, max): value as a 0.0..1.0 fraction of max (0 when max is zero or less).
def clamp_inside(r, bounds): Keep a rect inside bounds without resizing it.
def columns(r, count, gap = 0): Split a rect into count columns with gap between them.
def inset(r, amount): Shrink a rect by amount on all sides.
def screen_rect: The whole screen as a rect.
def ui_store: Persistent key/value store the UI widgets use for their own state (checkbox values, slider positions, menu selection).

entities

def spawn(klass = nil, attributes = {}): line 481
def despawn(entity): line 485
def despawn_if(&block): line 489
def each_entity(kind = nil, &block): line 493
def entities_of(kind): line 497
def entity_count(kind = nil): line 501
def colliding(rect, kind = nil): line 505
def move(entity, options = {}): line 509

animation

def animate(entity, name, options = {}): animate(entity, :run) animate(entity, :run, sheet: 'hero.png', frame_w: 16, frame_h: 20, frames: 6)
def animating?(entity, name = nil): line 521
def anim_done?(entity): line 525
def stop_anim(entity): line 529
def anim_state(entity): line 533
def draw_entity(entity, spec = {}): Draw an entity, resolving its active animation, tint and flips.

tweens and scheduling

def tween(target, property, options = {}): line 544
def tween_all(target, properties, options = {}): line 548
def after(ticks, &block): line 552
def every(ticks, options = {}, &block): line 556
def next_tick(&block): line 560

audio

def sfx(name, options = {}): line 566
def music(name, options = {}): line 570
def stop_music: line 574
def music_gain(value = nil): line 578
def mute: line 582
def unmute: line 586
def toggle_mute: line 590

assets

def assets_root: This cart's own directory, e.g. 'carts/space'. nil outside a cart.
def asset(path): Resolve a cart-relative path to a real one:
asset 'data/level.json' # => 'carts/space/data/level.json'
def shared_assets: Assets this cart is borrowing from the console root. Empty is the goal: a published cart ships its own directory alone.

sprites

def sprite(name): Resolve a sprite name to a path. Warns (visibly) if it is missing.
def auto_sprite(name, w = 16, h = 16, color = :accent, pattern = :solid): Resolve a sprite name, generating a placeholder texture if needed.
def draw_sprite(name, options = {}): Draw a sprite in one call.
def background(color = :dark): The screen background colour. Call once per frame if it changes.

layout

def strip(top_y, h, width = nil)

DragonRuby measures y from the bottom. For UI, thinking from the top is far more natural, so these wrap the same numbers:

draw.within ui.strip(0, 40) do ... end     # a 40px bar across the top

top(y) converts "y pixels down from the top" into the bottom-left origin, for when you want to place one item by hand. (DragonRuby also ships Numeric#from_top, e.g. y: 30.from_top, which does the same thing inline.)

def row_at(top_y, index, width, line_h, gap = 0)

line 651

def top(y)

line 655

levels

def load_map(path, options = {}): Load an LDTK level. Returns nil (with an on-screen warning) if the file is missing, so a bad level path is visible rather than a boot crash.
map = load_map 'maps/Level_0.ldtk' map.spawn_all @body = body entity: @ship, gravity: 0.4
def spawn_level(map, extra = {}): Spawn every entity from a loaded level into the entity store.

bodies

def body(options = {}): A kinematic platformer body. Takes one options hash -- see the note on Console::Body about why a positional list would not survive mruby.

misc

def on_enter(name, &block)

line 686

def on_leave(name, &block)

line 690

def debug(message)

line 694

def warn(message)

line 698

def start_text_input

Typed characters arrive via input.typed after enabling collection.

def stop_text_input

line 707

def typed

line 711

def tick_count

line 715

def frames_elapsed

line 719

def seconds

line 723

def oscillate(speed = 1.0, phase = 0.0)

A 0.0..1.0 ramp that repeats forever -- handy for idle motion.

def sine(speed = 1.0, phase = 0.0, amplitude = 1.0, center = 0.0)

line 732

def rand_int(min, max)

Random helpers with sane defaults for prototyping.

DragonRuby's rand takes at most one argument, so the console provides range helpers rather than making every cart remember the incantation.

def rand_between(min, max)

A random Float in min..max.

def pick(list)

line 751

def chance(probability = 0.5)

line 756