OSL
Install
Packages

raylib

Draw 2D and 3D graphics and read the keyboard and mouse in a raylib window, and use its colour, geometry and image helpers without one.

import "std:raylib"

std:raylib is a window you draw into, once per frame: shapes, text, textures, 2D and 3D cameras, shaders, keyboard and mouse. It suits games, simulations and anything that moves. For forms and buttons, use ui and window instead, or raygui for controls inside a raylib window.

Windows need SDL2 installed. Many helpers (colours, shapes for hit tests, cameras, image loading) work without a window, so the first examples run right here.

Colours#

Anything that takes a colour accepts a name, "#rrggbb", "#rgb", "#rrggbbaa" or {r, g, b, a}. raylib.color shows you what it understood:

main.osl
import "std:raylib"

log raylib.color("raywhite")
log raylib.color("#f80")
log raylib.color({r: 1, g: 2, b: 3, a: 4})
Click the code to edit it

Try "purple" or "#00ff0080". An unknown name throws a ValueError.

Points and hit tests#

raylib.vec(x, y) and raylib.vec3(x, y, z) build points. The isPoint... and is...Overlapping helpers answer the questions every game asks, with plain {x, y, width, height} rectangles and {x, y, radius} circles:

main.osl
import "std:raylib"

auto button = {x: 1, y: 1, width: 100, height: 40}
log raylib.isPointInRect(raylib.vec(50, 20), button)
log raylib.isPointInRect(raylib.vec(150, 20), button)

auto a = {x: 1, y: 1, radius: 5}
auto b = {x: 4, y: 1, radius: 5}
log raylib.isCircleOverlapping(a, b)
log raylib.isRectOverlapping(button, {x: 90, y: 30, width: 20, height: 20})
Click the code to edit it

Positions count from 1, like everything in OSL, so {x: 1, y: 1} is the top-left pixel.

Quick check

Which point is inside {x: 1, y: 1, width: 10, height: 10}?

Your first window#

raylib.initWindow opens a window, windowShouldClose() becomes true when the user closes it (or presses Escape), and raylib.draw(frame) draws one frame. Window code can't run here, so it is marked as compile-only. Copy it to your machine:

main.osl
import "std:raylib"

raylib.initWindow(800, 450, "Hello", {fps: 60}).unwrap()

while !raylib.windowShouldClose() (
  raylib.draw(def() (
    raylib.clear("#181825")
    raylib.text("Hello, World!", {x: 281, y: 201}, {size: 36, color: "#89b4fa"})
  ))
)

raylib.closeWindow()
Click the code to edit it

Change the colours and the text. Everything on screen is drawn inside raylib.draw.

The shorter loop#

raylib.runWindow(frame, options) opens the window, calls frame(ms) every frame with the time the last frame took, and closes the window at the end. background clears for you, and frames stops after that many frames (handy for tests):

main.osl
import "std:raylib"

number x = 20

raylib.runWindow(def(ms) (
  if raylib.isKeyDown("right") ( x += 0.3 * ms )
  if raylib.isKeyDown("left") ( x -= 0.3 * ms )
  raylib.rectangle({x: x, y: 200, width: 40, height: 40}, "#89b4fa")
  raylib.text("Arrow keys move the square", {x: 20, y: 20})
), {width: 800, height: 450, title: "Move", background: "#181825"})
Click the code to edit it

Multiplying by ms makes the speed the same on a slow computer and a fast one. Here the square moves 300 pixels a second.

Shapes and text#

rectangle, circle, line, polygon and pixel take geometry and a colour. A lineWidth option draws only the outline, radius rounds a rectangle:

main.osl
import "std:raylib"

raylib.runWindow(def(ms) (
  raylib.rectangle({x: 40, y: 40, width: 200, height: 100}, "#89b4fa", {radius: 12})
  raylib.rectangle({x: 40, y: 40, width: 200, height: 100}, "white", {lineWidth: 2})
  raylib.circle({x: 400, y: 90}, 40, "#f38ba8")
  raylib.line({x: 40, y: 200}, {x: 700, y: 260}, "#a6e3a1", {thickness: 3})
  raylib.polygon([{x: 500, y: 300}, {x: 600, y: 300}, {x: 550, y: 380}], "#f9e2af")
  raylib.text("Shapes", {x: 40, y: 300}, {size: 40, color: "white"})
), {background: "#181825", frames: 600})
Click the code to edit it

raylib.useFont(path, baseSize) makes text use a TTF or OTF font, and raylib.measureText(text, size) tells you how wide it will be, for centring.

Keyboard and mouse#

isKeyDown is true while a key is held, isKeyPressed only on the frame it went down. Keys are named ("space", "enter", "left", "f1") or a single character. The mouse has the same trio with buttons "left", "right" and "middle", plus mousePosition():

main.osl
import "std:raylib"

int clicks = 0
auto target = {x: 300, y: 150, width: 200, height: 100}

raylib.runWindow(def(ms) (
  auto mouse = raylib.mousePosition()
  auto over = raylib.isPointInRect(mouse, target)
  if over and raylib.isMousePressed("left") ( clicks += 1 )

  raylib.rectangle(target, if over then "#a6e3a1" else "#89b4fa")
  raylib.text("clicks: " ++ clicks, {x: 20, y: 20}, {size: 30, color: "white"})
), {background: "#181825"})
Click the code to edit it

nextChar() returns characters as they are typed, with the keyboard layout applied, which is what a text box wants.

Images and textures#

An image lives in memory, and a texture lives on the graphics card and is what you draw. raylib.loadTexture(path) loads a file as a texture, and tex.drawAt(position, options) draws it, with scale, rotation, tint and source (a part of the texture, for sprite sheets):

main.osl
import "std:raylib"

raylib.initWindow(640, 360, "Sprite").unwrap()
auto sprite = raylib.loadTexture("player.png").unwrap()
sprite.setFilter("bilinear").unwrap()

while !raylib.windowShouldClose() (
  raylib.draw(def() (
    raylib.clear("#181825")
    sprite.drawAt({x: 100, y: 100}, {scale: 2, tint: "white"})
  ))
)
raylib.closeWindow()
Click the code to edit it

Images from img work too: raylib.textureFromImage(pic) uploads one, so anything you drew with img can be shown, and raylib.screenshot() returns the window's contents as an *img.Image.

Loading an image without a window#

raylib.loadImage(path) needs no window. It returns a raylib.Image, and toImage() hands you a normal *img.Image:

main.osl
import "std:raylib"
import "std:img"
import "std:fs"

raylib.setLogLevel("none")
fs.remove("blue.png", {force: true}).unwrap()
img.new(4, 3, {fill: "#336699"}).save("blue.png").unwrap()

auto loaded = raylib.loadImage("blue.png").unwrap()
log loaded.width() loaded.height()

*img.Image pic = loaded.toImage()
log pic.pixel(1, 1)
fs.remove("blue.png").unwrap()
Click the code to edit it

A 2D camera#

raylib.camera2D({target, offset, zoom, rotation}) pans, zooms and rotates everything drawn inside cam.use(...). The target is the world point shown at the offset on screen. It also converts between the two, so a click can find the world point under it:

main.osl
import "std:raylib"

auto cam = raylib.camera2D({target: {x: 100, y: 100}, offset: {x: 50, y: 50}, zoom: 2})
log cam.toScreen({x: 100, y: 100})
log cam.toScreen({x: 110, y: 100})
log cam.toWorld({x: 50, y: 50})
Click the code to edit it

The world point 100, 100 appears at the screen's 50, 50, and 10 units to its right is 20 pixels away because of the zoom. Change zoom to 1 and run again. Inside a window:

main.osl
import "std:raylib"

auto cam = raylib.camera2D({offset: {x: 400, y: 225}, zoom: 1})

raylib.runWindow(def(ms) (
  if raylib.isKeyDown("a") ( cam.setZoom(cam.zoom() * 1.01) )
  if raylib.isKeyDown("z") ( cam.setZoom(cam.zoom() / 1.01) )
  cam.use(def() (
    raylib.circle({x: 0, y: 0}, 50, "#f38ba8")
    raylib.rectangle({x: 100, y: -20, width: 80, height: 40}, "#89b4fa")
  ))
), {background: "#181825"})
Click the code to edit it

3D#

raylib.camera({position, target, fovy}) is a 3D camera. Inside cam.use, cube, sphere, cylinder, plane, grid and line3D draw in world space. cam.control("orbital") moves the camera from the keyboard and mouse:

main.osl
import "std:raylib"

auto cam = raylib.camera({position: raylib.vec3(6, 5, 6), target: raylib.vec3(0, 1, 0), fovy: 60})

raylib.runWindow(def(ms) (
  cam.control("orbital")
  cam.use(def() (
    raylib.grid(10, 1)
    raylib.cube(raylib.vec3(0, 1, 0), raylib.vec3(2, 2, 2), "#89b4fa")
    raylib.cube(raylib.vec3(0, 1, 0), raylib.vec3(2, 2, 2), "white", {wireframe: true})
    raylib.sphere(raylib.vec3(3, 0.5, 0), 0.5, "#f38ba8")
  ))
), {background: "#181825"})
Click the code to edit it

Picking works with rays. raylib.ray(origin, direction).box(center, size) says whether it hits a box, and where:

main.osl
import "std:raylib"

auto ray = raylib.ray(raylib.vec3(0, 0, -10), raylib.vec3(0, 0, 1))
auto hit = ray.box(raylib.vec3(0, 0, 0), raylib.vec3(2, 2, 2))
log hit.hit hit.distance
log ray.box(raylib.vec3(5, 5, 5), raylib.vec3(1, 1, 1)).hit
Click the code to edit it

Render textures, blending and shaders#

raylib.renderTexture(w, h) is an off-screen surface. Draw into it with tex.use(...), then draw it on screen with tex.drawAt or save it with tex.toImage(). raylib.blend("additive", draw) changes how overlapping colours mix. raylib.compileShader(code) compiles a GPU shader, and shader.use(draw) draws through it. raylib.smoothLines(draw) draws anti-aliased lines in one batch.

Your turn

Hit test

A button is at {x: 10, y: 10, width: 100, height: 30}. Use raylib.isPointInRect to print, for each click point in the list, whether it hit the button.

main.osl
Ctrl Enter runs
Expected output
true
false
true
Your turn

Where does it appear?

A 2D camera looks at the world point 200, 100, shown at the screen point 400, 300, with no zoom. Print the screen position of the world point 250, 100.

main.osl
Ctrl Enter runs
Expected output
{"x":450,"y":300}

API reference#

186 members, generated from the std:raylib source of OSL 9.3.0.

Functions

#raylib.begin3D(*raylib.Camera camera) boolean

Deprecated. Deprecated: use camera.use(draw) instead.

begin3D starts drawing through a 3D camera.

#raylib.beginBlend(any mode)

Deprecated. Deprecated: use raylib.blend(mode, draw) instead.

beginBlend switches the blend mode; unknown modes mean "alpha".

#raylib.beginDrawing()

Deprecated. Deprecated: use raylib.draw(frame) instead, which ends the frame even when frame throws.

beginDrawing starts a frame.

#raylib.beginShader(*raylib.Shader s) boolean

Deprecated. Deprecated: use shader.use(draw) instead.

beginShader starts drawing through a shader and returns false for an invalid one.

#raylib.blend(string mode, any draw)

blend runs draw with a blend mode: "alpha" (normal), "additive", "multiply", "premultiplied", or "layer" (alpha blending that keeps a transparent render texture premultiplied, for compositing it later with "premultiplied"). Throws ValueError for an unknown mode.

#raylib.camera(object? options) *raylib.Camera

camera builds a 3D camera. Options: position and target ({x, y, z}, the camera's place and what it looks at; default the origin), up (default {x: 0, y: 1, z: 0}), fovy (vertical field of view in degrees, or the view height for an orthographic camera; default 60) and projection ("perspective", the default, or "orthographic").

#raylib.camera2D(object? options) *raylib.Camera2D

camera2D builds a 2D camera. Options: target (the world point {x, y} the camera looks at; default {x: 1, y: 1}), offset (where on screen that point appears, {x, y}; default {x: 1, y: 1}, the top-left pixel), rotation (degrees, default 0) and zoom (default 1). World points count from 1 like window positions, so the default camera draws everything where it would be drawn without one.

#raylib.centerRay(*raylib.Camera camera) *raylib.Ray

Deprecated. Deprecated: use camera.centerRay() instead.

centerRay returns the ray from a camera through the middle of the screen.

#raylib.circle(any center, number radius, any color, object? options)

circle draws a circle around a center {x, y}, filled unless lineWidth is given. Options: lineWidth (draw only the outline, this thick).

#raylib.circlesCollide(any first, any firstRadius, any second, any secondRadius) boolean

Deprecated. Deprecated: use raylib.isCircleOverlapping({x, y, radius}, {x, y, radius}) instead.

circlesCollide reports whether two circles overlap.

#raylib.clear(any color)

clear fills the whole drawing target with a color.

#raylib.closeWindow()

closeWindow closes the window and its graphics context. Closing when no window is open does nothing.

#raylib.color(any value) {a: int, b: int, g: int, r: int}

color reads a color and returns it as {r, g, b, a}. It accepts "#rrggbb", "#rrggbbaa", "#rgb", "#rgba", raylib's color names ("black", "white", "red", "green", "blue", "yellow", "orange", "purple", "pink", "gray", "transparent", "raywhite") and {r, g, b, a}; every raylib function that takes a color accepts the same. Throws ValueError for anything else.

#raylib.compileShader(string code, object? options) result<*raylib.Shader, error>

compileShader compiles a fragment shader for drawing. code is GLSL 330 or OSL-style shader code (see shader.transpile). Options: vertex (vertex shader code; default raylib's). Fails with StateError when no window is open and ParseError when the GPU driver rejects the code (raylib logs the driver's message).

#raylib.compileShaderFile(string path, object? options) result<*raylib.Shader, error>

compileShaderFile compiles a fragment shader from a file, like compileShader. Options: vertex (a vertex shader file; default raylib's). Fails with StateError when no window is open, NotFoundError or IOError when a file can't be read, and ParseError when the code doesn't compile.

#raylib.cube(any center, any size, any color, object? options)

cube draws a box around a center {x, y, z} with a size {x, y, z}. Options: wireframe (draw only the edges).

#raylib.cursorHidden() boolean

Deprecated. Deprecated: use raylib.isCursorHidden() instead.

cursorHidden reports whether the mouse cursor is hidden.

#raylib.cylinder(any from, any to, any color, object? options)

cylinder draws a cylinder or cone from one point {x, y, z} to another. Options: radius (default 1), topRadius (the radius at to; default radius, 0 makes a cone), slices (default 16) and wireframe.

#raylib.disableCursor()

disableCursor hides and locks the mouse cursor, for mouse-look controls.

#raylib.dpiScale() number

dpiScale returns framebuffer pixels per window unit (2 on most retina screens). It is measured rather than taken from the platform, which some backends report incorrectly.

#raylib.draw(any frame)

draw runs frame to draw one frame of the window and shows the result. Everything drawn on screen happens inside it. Throws StateError when no window is open.

#raylib.draw3D(*raylib.Camera camera, any frame) boolean

Deprecated. Deprecated: use camera.use(frame) instead.

draw3D runs frame drawing through a 3D camera.

#raylib.drawBillboard(*raylib.Camera camera, *raylib.Texture texture, any position, any size, any tint) boolean

Deprecated. Deprecated: use texture.drawBillboard(camera, position, {size, tint}) instead.

drawBillboard draws a texture facing the camera and returns false for a missing camera or invalid texture.

#raylib.drawCube(any center, any size, any color)

Deprecated. Deprecated: use raylib.cube(center, size, color) instead.

drawCube draws a solid box.

#raylib.drawCubeWires(any center, any size, any color)

Deprecated. Deprecated: use raylib.cube(center, size, color, {wireframe: true}) instead.

drawCubeWires draws a box's edges.

#raylib.drawCylinder(any position, any radiusTop, any radiusBottom, any height, any slices, any color)

Deprecated. Deprecated: use raylib.cylinder(from, to, color, {radius, topRadius, slices}) instead.

drawCylinder draws a cylinder standing on position.

#raylib.drawGrid(any slices, any spacing)

Deprecated. Deprecated: use raylib.grid(slices, spacing) instead.

drawGrid draws a ground grid.

#raylib.drawLine3D(any start, any end, any color)

Deprecated. Deprecated: use raylib.line3D(from, to, color) instead.

drawLine3D draws a 3D line.

#raylib.drawPlane(any center, any size, any color)

Deprecated. Deprecated: use raylib.plane(center, {x, z}, color) instead.

drawPlane draws a ground rectangle.

#raylib.drawSphere(any center, any radius, any color)

Deprecated. Deprecated: use raylib.sphere(center, radius, color) instead.

drawSphere draws a solid sphere.

#raylib.drawSphereWires(any center, any radius, any rings, any slices, any color)

Deprecated. Deprecated: use raylib.sphere(center, radius, color, {wireframe: true, rings, slices}) instead.

drawSphereWires draws a sphere's wireframe.

#raylib.drawToTexture(*raylib.RenderTexture target, any drawFunc) boolean

Deprecated. Deprecated: use renderTexture.use(draw) instead.

drawToTexture runs drawFunc drawing into a render texture and returns false for an invalid one.

#raylib.elapsed() number

elapsed returns the milliseconds since the window was opened.

#raylib.enableCursor()

enableCursor shows and unlocks the mouse cursor.

#raylib.end3D()

Deprecated. Deprecated: use camera.use(draw) instead.

end3D stops drawing through a 3D camera.

#raylib.endBlend()

Deprecated. Deprecated: use raylib.blend(mode, draw) instead.

endBlend restores normal alpha blending.

#raylib.endDrawing()

Deprecated. Deprecated: use raylib.draw(frame) instead.

endDrawing ends a frame and shows it.

#raylib.endShader()

Deprecated. Deprecated: use shader.use(draw) instead.

endShader stops drawing through a shader.

#raylib.fps() int

fps returns the frames drawn in the last second.

#raylib.frameDuration() number

frameDuration returns how long the last frame took, in milliseconds.

#raylib.frameTime() number

Deprecated. Deprecated: use raylib.frameDuration() instead; it returns milliseconds.

frameTime returns how long the last frame took, in seconds.

#raylib.gpuPreference() string

gpuPreference returns "integrated" or "discrete".

#raylib.grid(int slices, number spacing)

grid draws a ground grid of slices by slices squares, spacing apart, centred on the origin.

#raylib.initWindow(int width, int height, string title, object? options) result<unit, error>

initWindow opens the program's window, width by height window units, and its graphics context; most other functions need it open. Options: fps (frames per second to aim for) and the window flags highdpi, resizable, vsync, msaa, transparent, undecorated, borderless, topmost, hidden and alwaysRun (booleans, default false). A hidden window can show for a moment as it opens, since SDL2 opens every window shown. Throws ValueError for transparent, which SDL2's windows can't be. Fails with StateError when a window is already open and RuntimeError when one can't be opened.

#raylib.isCircleOverlapping(any a, any b) boolean

isCircleOverlapping reports whether two circles {x, y, radius} overlap.

#raylib.isCursorHidden() boolean

isCursorHidden reports whether the mouse cursor is hidden.

#raylib.isKeyDown(string key) boolean

isKeyDown reports whether key is held down. Keys are named as for isKeyPressed.

#raylib.isKeyPressed(string key) boolean

isKeyPressed reports whether key went down this frame. Keys are names ("space", "escape", "enter", "tab", "backspace", "insert", "delete", arrow keys "left"/"right"/"up"/"down", "pageup", "pagedown", "home", "end", "shift", "ctrl", "alt" and their "left"/"right" forms, "f1" to "f12") or single characters ("a", "1", "/"). Throws ValueError for an unknown key.

#raylib.isKeyReleased(string key) boolean

isKeyReleased reports whether key came up this frame. Keys are named as for isKeyPressed.

#raylib.isMouseDown(string button) boolean

isMouseDown reports whether a mouse button is held down. Buttons are named as for isMousePressed.

#raylib.isMousePressed(string button) boolean

isMousePressed reports whether a mouse button ("left", "right", "middle", "side" or "extra") went down this frame. Throws ValueError for an unknown button.

#raylib.isMouseReleased(string button) boolean

isMouseReleased reports whether a mouse button came up this frame. Buttons are named as for isMousePressed.

#raylib.isPointInCircle(any point, any circle) boolean

isPointInCircle reports whether a point {x, y} is inside a circle {x, y, radius}.

#raylib.isPointInRect(any point, any rect) boolean

isPointInRect reports whether a point {x, y} is inside a rectangle {x, y, width, height}.

#raylib.isRectOverlapping(any a, any b) boolean

isRectOverlapping reports whether two rectangles {x, y, width, height} overlap.

#raylib.isWindowReady() boolean

isWindowReady reports whether a window is open.

#raylib.keyDown(any key) boolean

Deprecated. Deprecated: use raylib.isKeyDown(key) instead.

keyDown reports whether a key, by name or key code, is held down.

#raylib.keyPressed(any key) boolean

Deprecated. Deprecated: use raylib.isKeyPressed(key) instead.

keyPressed reports whether a key, by name or key code, went down this frame.

#raylib.keyReleased(any key) boolean

Deprecated. Deprecated: use raylib.isKeyReleased(key) instead.

keyReleased reports whether a key, by name or key code, came up this frame.

#raylib.line(any from, any to, any color, object? options)

line draws a straight line between two points {x, y}. Options: thickness (default 1).

#raylib.line3D(any from, any to, any color)

line3D draws a line between two points {x, y, z}.

#raylib.loadFragmentShader(any fs) *raylib.Shader

Deprecated. Deprecated: use raylib.compileShader(code) or raylib.compileShaderFile(path) instead.

loadFragmentShader loads a fragment shader from a file or code; check valid() afterwards.

#raylib.loadImage(string path) result<*raylib.Image, error>

loadImage loads an image file (PNG, BMP, TGA, JPEG, GIF, QOI, HDR, PSD, ...) into memory; no window is needed. Fails with NotFoundError or IOError when the file can't be read and ParseError when it isn't an image raylib can decode.

#raylib.loadSVG(string path, number scale) result<*raylib.Image, error>

loadSVG rasterises an SVG file at scale, rounding the size up and stretching the drawing to fill it. Fails with NotFoundError or IOError when the file can't be read, ParseError when it isn't an SVG with a size, and ValueError when the image would be over 67 million pixels; throws ValueError for a scale that isn't positive.

#raylib.loadSVGCanvas(string path, number scale) result<*raylib.Image, error>

loadSVGCanvas rasterises an SVG the way a browser draws it onto a canvas that is width * scale by height * scale (sizes truncated, as canvas dimensions are), with the drawing at exactly that scale. Fails like loadSVG.

#raylib.loadShader(any vs, any fs) *raylib.Shader

Deprecated. Deprecated: use raylib.compileShader(code, {vertex}) or raylib.compileShaderFile(path, {vertex}) instead.

loadShader loads a vertex and fragment shader, each from a file when one exists at that path and as code otherwise; check valid() afterwards.

#raylib.loadTexture(string path) result<*raylib.Texture, error>

loadTexture loads an image file (PNG, BMP, TGA, JPEG, GIF, QOI, HDR, PSD, ...) onto the GPU. Fails with StateError when no window is open, NotFoundError or IOError when the file can't be read, and ParseError when it isn't an image raylib can decode.

#raylib.measureText(string text, number size) int

measureText returns how wide text is at an em size, in window units.

#raylib.mouseDelta() {x: number, y: number}

mouseDelta returns how far the mouse moved {x, y} since the last frame.

#raylib.mouseDown(any button) boolean

Deprecated. Deprecated: use raylib.isMouseDown(button) instead.

mouseDown reports whether a mouse button is held down.

#raylib.mousePosition() {x: number, y: number}

mousePosition returns the mouse position {x, y} in window units, 1, 1 over the top-left pixel, the way drawing calls take positions.

#raylib.mousePressed(any button) boolean

Deprecated. Deprecated: use raylib.isMousePressed(button) instead.

mousePressed reports whether a mouse button, by name or number, went down this frame; unknown names mean the left button.

#raylib.mouseReleased(any button) boolean

Deprecated. Deprecated: use raylib.isMouseReleased(button) instead.

mouseReleased reports whether a mouse button came up this frame.

#raylib.mouseWheel() number

mouseWheel returns how far the mouse wheel turned this frame; positive is away from the user.

#raylib.nextChar() string?

nextChar returns the next character typed since the last call, with shift and the keyboard layout applied, or null when the queue is empty.

#raylib.nextKey() string?

nextKey returns the next key pressed since the last call, named as isKeyPressed names keys, or null when the queue is empty. Keys without a name are skipped.

#raylib.off(string event, any handler)

off removes a handler added with on. Removing one that isn't registered does nothing.

#raylib.on(string event, any handler)

on adds handler for an event. "resize" runs while the window is being resized by dragging its edge: on macOS the program's loop is paused until the drag ends, so the handler is the only chance to redraw (fit the content, then draw a frame) during it. Throws ValueError for an unknown event.

#raylib.onResize(any handler)

Deprecated. Deprecated: use raylib.on("resize", handler) instead.

onResize sets the one handler run while the window is being resized, replacing any earlier one.

#raylib.pixel(any point, any color)

pixel draws one pixel at a point {x, y}; {x: 1, y: 1} is the top-left pixel.

#raylib.plane(any center, any size, any color)

plane draws a flat rectangle on the ground (the x-z plane) around a center {x, y, z}, size {x, z} across.

#raylib.pointInRectangle(any point, any rectangle) boolean

Deprecated. Deprecated: use raylib.isPointInRect(point, rect) instead.

pointInRectangle reports whether a point is inside a rectangle.

#raylib.polygon(array points, any color, object? options)

polygon draws a convex polygon through three or more points {x, y}, in either winding order, filled unless lineWidth is given. Options: lineWidth (draw only the outline, this thick).

#raylib.pressedChar() string

Deprecated. Deprecated: use raylib.nextChar() instead; it returns null when there is none.

pressedChar returns the next typed character, or "" when there is none.

#raylib.pressedKey() string

Deprecated. Deprecated: use raylib.nextKey() instead; it returns null when there is none.

pressedKey returns the next pressed key's name, or "" when there is none.

#raylib.ray(any origin, any direction) *raylib.Ray

ray builds a ray from an origin {x, y, z} in a direction {x, y, z}.

#raylib.rect(any x, any y, any width, any height) object

Deprecated. Deprecated: write the object {x, y, width, height} instead.

rect builds a rectangle {x, y, width, height}.

#raylib.rectangle(any rect, any color, object? options)

rectangle draws a rectangle {x, y, width, height}, x, y its top-left corner, filled unless lineWidth is given. Options: lineWidth (draw only the outline, this thick) and radius (round the corners by this many units).

#raylib.rectanglesCollide(any first, any second) boolean

Deprecated. Deprecated: use raylib.isRectOverlapping(a, b) instead.

rectanglesCollide reports whether two rectangles overlap.

#raylib.renderTexture(int width, int height) result<*raylib.RenderTexture, error>

renderTexture makes an off-screen texture of width by height pixels to draw into with use(), then draw on screen with drawAt() or pass to a shader. Fails with StateError when no window is open and RuntimeError when the GPU can't make one; throws ValueError for a size that isn't positive.

#raylib.run(object options, any update, any draw)

Deprecated. Deprecated: use raylib.runWindow(frame, options) instead; frame gets milliseconds.

run opens a window from an options object and calls update(seconds) and draw() once a frame until the window closes.

#raylib.runWindow(any frame, object? options) result<unit, error>

runWindow opens a window, calls frame(ms) once a frame inside draw with the previous frame's duration in milliseconds until the window is asked to close, then closes it. Options: width (default 800), height (450), title ("OSL raylib"), fps (60), background (a color to clear each frame to), frames (stop after this many; 0, the default, runs until closed) and the window flags of initWindow. When a window is already open it is used and left open. Fails with RuntimeError when a window can't be opened.

#raylib.screenSize() {height: int, width: int}

screenSize returns the window's {width, height} in window units.

#raylib.screenshot() result<*img.Image, error>

screenshot returns what the window shows as a new img.Image from std:img, at the framebuffer's full resolution on high-DPI screens and fully opaque. Fails with StateError when no window is open.

#raylib.setConfigFlags(any flags)

Deprecated. Deprecated: pass flags as initWindow options instead, such as {highdpi: true, resizable: true}.

setConfigFlags sets window flags for the next window from a "a|b" string, an array of names, or a number; unknown names are ignored.

#raylib.setGPUPreference(string preference) string

setGPUPreference chooses the GPU for windows opened afterwards: "integrated" (the default, lower power) or "discrete" ("dedicated" and "high_performance" mean the same). It returns the preference now in effect. Throws ValueError for anything else.

#raylib.setLogLevel(string level)

setLogLevel sets which of raylib's own log messages are printed: "all", "trace", "debug", "info" (raylib's default), "warning", "error", "fatal" or "none". Throws ValueError for anything else.

#raylib.setMousePosition(number x, number y)

setMousePosition moves the mouse cursor to x, y in window units, 1, 1 being the top-left pixel as for mousePosition.

#raylib.setSVGFont(string family, string path) boolean

Deprecated. Deprecated: use svg.addFont(family, path) instead.

setSVGFont registers the font file used for SVG text in a font family and returns false when it can't be loaded.

#raylib.setTargetFPS(int fps)

setTargetFPS caps the frame rate; 0 means no cap.

#raylib.setWindowSize(int width, int height)

setWindowSize resizes the window to width by height window units. Throws StateError when no window is open.

#raylib.setWindowTitle(string title)

setWindowTitle changes the window's title. Throws StateError when no window is open.

#raylib.shader(any code) *raylib.Shader

Deprecated. Deprecated: use raylib.compileShader(code) instead.

shader loads a fragment shader from a file or code; check valid() afterwards.

#raylib.smoothLine(any from, any to, any color, object? options)

smoothLine draws an antialiased line with round caps between two points {x, y}; a zero-length line draws a round dot. Options: thickness (default 1). Throws StateError outside raylib.smoothLines.

#raylib.smoothLines(any draw) result<unit, error>

smoothLines runs draw, in which smoothLine draws antialiased round-capped lines with premultiplied alpha, all sent to the GPU in one batch at the end. Fails with StateError when no window is open and RuntimeError when the line shader doesn't compile.

#raylib.sphere(any center, number radius, any color, object? options)

sphere draws a sphere around a center {x, y, z}. Options: wireframe, rings (default 16) and slices (default 16).

#raylib.svgSize(string path, number scale) int[]

Deprecated. Deprecated: use raylib.loadSVG(path, scale) and the image's width() and height() instead.

svgSize returns the [width, height] loadSVG gives an SVG at scale, or [0, 0].

#raylib.svgViewBox(string path) number[]

Deprecated. Deprecated: use svg.infoFile(path) instead.

svgViewBox returns an SVG file's viewBox as [x, y, width, height], or zeros.

#raylib.takeScreenshot(string path) result<unit, error>

takeScreenshot saves what the window shows to an image file (PNG by extension). Fails with StateError when no window is open and IOError when the file can't be written.

#raylib.text(string text, any position, object? options)

text draws text with its top-left corner at a point {x, y}. Options: size (em size, default 20) and color (default "#000000").

#raylib.textHeight(number size) number

textHeight returns the line height text uses for an em size: the font's ascent plus descent, or the size itself with raylib's default font.

#raylib.textureFromImage(*img.Image image, object? options) result<*raylib.Texture, error>

textureFromImage uploads an img.Image from std:img to the GPU as a texture, so anything drawn with img can be shown in the window. Later changes to the image don't reach the texture. Options: premultiplied, as for Image.toTexture. Fails with StateError when no window is open; throws StateError when the image is closed and TypeError for null.

#raylib.time() number

Deprecated. Deprecated: use raylib.elapsed() instead; it returns milliseconds.

time returns the seconds since the window was opened.

#raylib.useFont(string path, int baseSize) result<unit, error>

useFont makes text and measureText use a TTF or OTF font, rasterised at baseSize pixels and smoothly scaled; sizes passed to them are em sizes, as in CSS. Fails with StateError when no window is open, NotFoundError or IOError when the file can't be read, and ParseError when it isn't a font.

#raylib.vec(number x, number y) {x: number, y: number}

vec builds a 2D point {x, y}.

#raylib.vec3(number x, number y, number z) {x: number, y: number, z: number}

vec3 builds a 3D point {x, y, z}.

#raylib.windowReady() boolean

Deprecated. Deprecated: use raylib.isWindowReady() instead.

windowReady reports whether a window is open.

#raylib.windowShouldClose() boolean

windowShouldClose reports whether the user asked to close the window (its close button or Escape). Throws StateError when no window is open.

*raylib.Texture

#texture.close()

close frees the texture's GPU memory. A texture from a render texture's texture() belongs to it and is freed with it; closing that one only stops it being used. Closing twice does nothing; drawing a closed texture throws StateError.

#texture.drawAt(any position, object? options)

drawAt draws the texture with its top-left corner at a point {x, y}. Options: scale (default 1), rotation (degrees around origin, default 0), tint (a color multiplied in, default "#ffffff"), source (the part of the texture to draw, {x, y, width, height} in texture pixels with x, y its top-left pixel, 1, 1 for the texture's corner; default all of it; a negative width or height flips it), width and height (the drawn size; default the source size times scale) and origin (how far {x, y} from the drawn rectangle's top-left corner the point is that position and rotation refer to; default {x: 0, y: 0}). Throws StateError when the texture is closed.

#texture.drawBillboard(*raylib.Camera camera, any position, object? options)

drawBillboard draws the texture in 3D at a point {x, y, z}, always facing the camera. Call it inside camera.use. Options: size (world units tall, default 1) and tint (default "#ffffff"). Throws StateError when the texture is closed.

#texture.height() int

height returns the texture's height in pixels.

#texture.isClosed() boolean

isClosed reports whether the texture has been closed, or belongs to a render texture that has.

#texture.setFilter(string mode) result<unit, error>

setFilter sets how the texture is sampled when scaled: "point" (sharp pixels, the default), "bilinear" or "trilinear" (smooth, with mipmaps). Fails with StateError when the texture is closed; throws ValueError for an unknown mode.

#texture.setWrap(string mode) result<unit, error>

setWrap sets how sampling beyond the texture's edges behaves: "repeat" (the default), "clamp" (edge pixels extend outwards) or "mirror". Fails with StateError when the texture is closed; throws ValueError for an unknown mode.

#texture.unload() boolean

Deprecated. Deprecated: use texture.close() instead.

unload frees the texture and returns false when it was already unloaded.

#texture.valid() boolean

Deprecated. Deprecated: loaders now fail with a result instead of returning invalid textures; use isClosed() for closed ones.

valid reports whether the texture loaded and hasn't been unloaded.

#texture.width() int

width returns the texture's width in pixels.

*raylib.Image

#image.close()

close frees the image's memory. Closing twice does nothing; any other use afterwards throws StateError.

#image.height() int

height returns the image's height in pixels. Throws StateError when the image is closed.

#image.isClosed() boolean

isClosed reports whether the image has been closed.

#image.pixels() int[]

pixels returns every pixel row by row from the top left, each packed as one 0xRRGGBBAA number. Throws StateError when the image is closed.

#image.premultipliedTexture() *raylib.Texture

Deprecated. Deprecated: use image.toTexture({premultiplied: true}) instead.

premultipliedTexture uploads a premultiplied copy of the image, returning an invalid texture when it can't.

#image.save(string path) result<unit, error>

save writes the image to a file (PNG by extension), alpha included. Fails with IOError when the file can't be written; throws StateError when the image is closed.

#image.texture() *raylib.Texture

Deprecated. Deprecated: use image.toTexture() instead.

texture uploads the image to the GPU, returning an invalid texture when it can't.

#image.toImage() *img.Image

toImage copies the image into a new img.Image from std:img, to draw on, filter or encode it there; the two don't share pixels. Throws StateError when the image is closed.

#image.toTexture(object? options) result<*raylib.Texture, error>

toTexture uploads the image to the GPU as a texture. Options: premultiplied (multiply color by alpha first, for drawing inside raylib.blend("premultiplied", ...); linear filtering of such a texture doesn't darken the edges of transparent areas). Fails with StateError when no window is open; throws StateError when the image is closed.

#image.unload() boolean

Deprecated. Deprecated: use image.close() instead.

unload frees the image and returns false when it was already unloaded.

#image.valid() boolean

Deprecated. Deprecated: loaders now fail with a result instead of returning invalid images; use isClosed() for closed ones.

valid reports whether the image loaded and hasn't been unloaded.

#image.width() int

width returns the image's width in pixels. Throws StateError when the image is closed.

*raylib.Camera

#camera.centerRay() *raylib.Ray

centerRay returns the ray from the camera through the middle of the screen.

#camera.control(string mode)

control moves the camera from this frame's keyboard and mouse input the way raylib's camera modes do: "free" (fly with WASD and the mouse), "orbital" (circle the target), "firstPerson" or "thirdPerson". Throws ValueError for an unknown mode.

#camera.position() {x: number, y: number, z: number}

position returns where the camera is, {x, y, z}.

#camera.screenRay(any point) *raylib.Ray

screenRay returns the ray from the camera through a point {x, y} on the screen, such as the mouse position.

#camera.setPosition(any position) result<unit, error>

setPosition moves the camera to a point {x, y, z}. It always succeeds.

#camera.setTarget(any target) result<unit, error>

setTarget points the camera at a point {x, y, z}. It always succeeds.

#camera.target() {x: number, y: number, z: number}

target returns the point {x, y, z} the camera looks at.

#camera.update(any ...modes) boolean

Deprecated. Deprecated: use camera.control(mode) instead.

update moves the camera from input in a mode ("free" by default); unknown modes mean "free".

#camera.use(any draw)

use runs draw with 3D drawing (cube, sphere, ...) seen through this camera. Call it inside raylib.draw.

*raylib.Camera2D

#camera2D.offset() {x: number, y: number}

offset returns where on screen the target appears, {x, y}.

#camera2D.rotation() number

rotation returns the camera's rotation in degrees.

#camera2D.setOffset(any offset)

setOffset sets where on screen the target appears, {x, y}.

#camera2D.setRotation(number degrees)

setRotation sets the camera's rotation in degrees.

#camera2D.setTarget(any target)

setTarget sets the world point {x, y} the camera looks at.

#camera2D.setZoom(number zoom)

setZoom sets the camera's zoom. Throws ValueError unless it is more than 0.

#camera2D.target() {x: number, y: number}

target returns the world point {x, y} the camera looks at.

#camera2D.toScreen(any point) {x: number, y: number}

toScreen converts a world point {x, y} to where it appears on screen.

#camera2D.toWorld(any point) {x: number, y: number}

toWorld converts a screen point {x, y}, such as the mouse position, to the world point under it.

#camera2D.use(any draw)

use runs draw with drawing panned, rotated and zoomed by this camera. Call it inside raylib.draw.

#camera2D.zoom() number

zoom returns the camera's zoom; 2 draws everything twice as large.

*raylib.Ray

#ray.box(any center, any size) {distance: number?, hit: boolean, normal: {x: number, y: number, z: number}?, point: {x: number, y: number, z: number}?}

box returns where the ray first meets a box around a center {x, y, z} with a size {x, y, z}: {hit, distance, point, normal}, where distance, point and normal are null when hit is false.

*raylib.Shader

#shader.begin() boolean

Deprecated. Deprecated: use shader.use(draw) instead.

begin starts drawing through the shader and returns false for an invalid one.

#shader.close()

close frees the shader. Closing twice does nothing; any other use afterwards throws StateError.

#shader.drawFullscreen() result<unit, error>

drawFullscreen fills the whole window with white drawn through this shader. Fails with StateError when the shader is closed or no window is open.

#shader.drawRect(any rect)

drawRect fills a rectangle {x, y, width, height} with white drawn through this shader. Throws StateError when the shader is closed.

#shader.end()

Deprecated. Deprecated: use shader.use(draw) instead.

end stops drawing through the shader.

#shader.hasUniform(string name) boolean

hasUniform reports whether the shader has a uniform with this name. GLSL drops uniforms the code doesn't use.

#shader.isClosed() boolean

isClosed reports whether the shader has been closed.

#shader.setUniform(string name, any value) result<unit, error>

setUniform sets a uniform: a number (float), an array of 1 to 4 numbers or a vector {x, y}, {x, y, z} or {x, y, z, w} (float to vec4), a color {r, g, b, a} (vec4 of 0-255 channels), or a texture or render texture (sampler2D). Setting a uniform the shader doesn't have does nothing, since GLSL drops unused ones (see hasUniform). Fails with StateError when the shader is closed; throws TypeError for any other value.

#shader.setValue(any name, any value) boolean

Deprecated. Deprecated: use shader.setUniform(name, value) instead.

setValue sets a uniform and returns false when the shader is invalid, has no such uniform, or the value can't be used.

#shader.unload() boolean

Deprecated. Deprecated: use shader.close() instead.

unload frees the shader and returns false when it was invalid or already unloaded.

#shader.use(any draw)

use runs draw with everything it draws passed through this shader. Call it inside raylib.draw. Throws StateError when the shader is closed.

#shader.valid() boolean

Deprecated. Deprecated: raylib.compileShader fails with a result instead of returning invalid shaders; use isClosed() for closed ones.

valid reports whether the shader compiled and hasn't been unloaded.

*raylib.RenderTexture

#renderTexture.begin() boolean

Deprecated. Deprecated: use renderTexture.use(draw) instead.

begin starts drawing into the render texture and returns false for an invalid one.

#renderTexture.close()

close frees the render texture, and the textures texture() returned with it. Closing twice does nothing; any other use afterwards throws StateError.

#renderTexture.drawAt(any position, object? options)

drawAt draws the render texture's contents the right way up with the top-left corner at a point {x, y}. Takes the options of Texture.drawAt. Throws StateError when the render texture is closed.

#renderTexture.end()

Deprecated. Deprecated: use renderTexture.use(draw) instead.

end stops drawing into the render texture.

#renderTexture.height() int

height returns the render texture's height in pixels.

#renderTexture.isClosed() boolean

isClosed reports whether the render texture has been closed.

#renderTexture.save(string path) result<unit, error>

save writes the render texture's contents to an image file (PNG by extension), the right way up and fully opaque. Fails with IOError when the file can't be written; throws StateError when the render texture is closed.

#renderTexture.texture() *raylib.Texture

texture returns the render texture's contents as a texture, for setUniform or drawing with texture options. It shares the render texture's GPU memory: it is upside down (OpenGL stores rows bottom-up), closing it doesn't free anything, and it stops working when the render texture is closed. Throws StateError when the render texture is closed.

#renderTexture.toImage() *img.Image

toImage copies the render texture's contents into a new img.Image from std:img, the right way up and with the alpha it was drawn with. Throws StateError when the render texture is closed.

#renderTexture.unload() boolean

Deprecated. Deprecated: use renderTexture.close() instead.

unload frees the render texture and returns false when it was invalid or already unloaded.

#renderTexture.use(any draw)

use runs draw with everything it draws going into this texture instead of the screen. Throws StateError when the render texture is closed.

#renderTexture.valid() boolean

Deprecated. Deprecated: raylib.renderTexture fails with a result instead of returning invalid render textures; use isClosed() for closed ones.

valid reports whether the render texture was made and hasn't been unloaded.

#renderTexture.width() int

width returns the render texture's width in pixels.

Edit this page View as Markdown