Ray 低阶 API 参考

Low Level API (Engine.*) 是为多样化的 2D 游戏制作而设计的。

每个 API 函式都只接受一个引数。 该引数必须是字典，而引数必须以键值对方式存放。

骨架

// 请勿在函式外定义变数，这会造成语法错误。

// 视窗建立时呼叫。
func setup() {
    // 回传视窗设定。
    return {
        width: 1280,
        height: 720,
        title: "My First Game"
    };
}

// 游戏开始时只呼叫一次。
func start() {
    // 全域变数应该在这里定义。
    posX = 0;
    posY = 0;

    // 建立一张白色的 100x100 纹理。
    tex = Engine.createColorTexture({
        width: 100,
        height: 100,
        r: 255, g: 255, b: 255, a: 255
    });
}

// 每一帧在渲染前呼叫。
func update() {
    posX = Engine.mousePosX;
    posY = Engine.mousePosY;
}

// 每一帧用来绘制图形。
func render() {
    Engine.draw({ texture: tex, x: posX, y: posY });
}

除错

print()

这个 API 会列印字串或转储物件。 只接受非字典引数。

func dumpEnemies() {
    if (Engine.isGamepadXPressed) {
        print("[Current emenies]");
        print(enemies);
    }
}

时间

绝对时间

func update() {
    // 取得距离上次呼叫经过的秒数。
    var curTime = Engine.millisec;
    var dt = (curTime - lastTime) * 0.001;
    lastTime = curTime;

    updateCharacters(dt);
}

Engine.getDate()

回传日期字典。

func frame() {
    var date = Engine.getDate({});

    var year  = date.year;
    var month = date.month;
    var day   = date.day;
    var hour  = date.hour;
    var min   = date.minute;
    var sec   = date.second;
}

输入

以下是变数，不是函式。

func update() { if (Engine.isMouseLeftPressed) { player.x = player.x + 100; } }

Rendering

Engine.createColorTexture()

此 API 会以指定颜色建立一个材质贴图并回传。

func createBlockTexture() { blockTex = Engine.createColorTexture({ width: 16, height: 16, r: 255, g: 255, b: 255, a: 255 }); }

Engine.loadTexture()

此 API 会从资产载入贴图并回传。

` func loadPlayerTexture() { playerTex = Engine.loadTexture({ file: "player.png" });

var width = playerTex.width; var height = playerTex.height; } `

Engine.destroyTexture()

此 API 会销毁贴图。

func destroyPlayerTexture() { Engine.loadTexture({ texture: playerTex }); }

Engine.renderTexture()

此 API 会将贴图渲染到画面上。

func renderPlayer() { Engine.renderTexture({ dstLeft: playerPos.x, dstTop: playerPos.y, dstWidth: playerTex.width, dstHeight: playerTex.height, texture: playerTex, srcLeft: 0, srcTop: 0, srcWidth: playerTex.width, srcHeight: playerTex.height, alpha: 255 }); }

Engine.draw()

此 API 会将贴图渲染到画面上（比 Engine.renderTexture() 更简单的版本）。

func renderPlayer() { Engine.draw({ texture: playerTex, x: playerPos.x, y: playerPos.y }); }

Engine.renderTexture3D()

此 API 会将贴图渲染到画面上。

func renderPlayer3D() { Engine.renderTexture3D({ x1: playerPos.x, y1: playerPos.y, x2: playerPos.x + playerTex.width, y2: playerPos.y, x3: playerPos.x + playerTex.width, y3: playerPos.y + playerTex.height, x4: playerPos.x, y4: playerPos.y + playerTex.height, texture: playerTex, srcLeft: 0, srcTop: 0, srcWidth: playerTex.width, srcHeight: playerTex.height, alpha: 255 }); }

Engine.loadFont()

此 API 会将资产字型档载入到指定字型槽。

func loadNotoSansFont() { Engine.loadFont({ slot: 0, file: "NotoSans.ttf" }); }

Engine.createTextTexture()

此 API 会建立贴图并在其上绘制文字。

func createScoreTexture() { scoreTex = Engine.createTextTexture({ slot: 0, text: "Score: " + score, size: 32, r: 255, g: 255, b: 255, a: 255 }); }

Sound

Engine.playSound()

此 API 会开始播放指定音效资产档。

func playJumpSound() { Engine.playSound({ stream: 0, file: "jump.ogg" }); }

Engine.playSoundLoop()

此 API 会开始播放指定音效资产档。

func playBGM() { Engine.playSoundLoop({ stream: 0, file: "jump.ogg" }); }

Engine.stopSound()

此 API 会停止指定音轨上的音效播放。

func playJumpSound() { Engine.stopSound({ stream: 0 }); }

Engine.setSoundVolume()

此 API 会设定指定音轨的音量。

func playJumpSound() { Engine.setSoundVolume({ stream: 0, volume: 1.0 }); }

Save Data

Engine.writeSaveData()

此 API 会写入与 key 字串对应的存档资料值。 如果存档资料值太大，这个 API 会失败。

Engine.readSaveData()

此 API 会读取与 key 字串对应的存档资料值。 回传值会是一个代表存档资料值的物件。 当指定的 key 不可用时，此 API 会失败。

Engine.checkSaveData()

此 API 会检查指定 key 字串是否存在存档资料。 回传值为布林值。