Skip to content

getting-started.md

Latest commit

 

History

History
137 lines (98 loc) · 3.69 KB

getting-started.md

File metadata and controls

137 lines (98 loc) · 3.69 KB
Raw

Getting Started

This guide takes a clean checkout to a validated AngelScript.dll.

Prerequisites

  • Windows.
  • Visual Studio 2022 with C++ build tools.
  • Virtools SDK 2.1 or newer.
  • DynCall, DynCallback, and DynLoad libraries, only when configuring with -DCKAS_ENABLE_DYNCALL=ON.
  • AngelScript source under deps/angelscript; if it is missing, CMake downloads the SDK from AngelCode.

For offline builds, pass -DCKAS_ANGELSCRIPT_ARCHIVE=C:\Path\To\angelscript_2.38.0.zip. Use CKAS_ANGELSCRIPT_URL and CKAS_ANGELSCRIPT_SHA256 when pointing CMake at a mirror or a different SDK archive.

The plugin is built as 32-bit for supported Virtools 2.x hosts.

Configure and Build

git submodule update --init --recursive

cmake -B build -G "Visual Studio 17 2022" -A Win32 `
  -DVIRTOOLS_SDK_PATH=C:\Path\To\VirtoolsSDK `
  -DCKAS_ENABLE_DYNCALL=ON `
  -DDYNCALL_ROOT=C:\Path\To\dyncall `
  -DDYNCALLBACK_ROOT=C:\Path\To\dyncall `
  -DDYNLOAD_ROOT=C:\Path\To\dyncall `
  -DCKAS_BUILD_SELF_TESTS=ON

cmake --build build --config Release

The DLL is written to:

build\src\Release\AngelScript.dll

Install it into the host:

Copy-Item build\src\Release\AngelScript.dll C:\Path\To\Virtools\BuildingBlocks\

Create a distributable ZIP:

cmake --build build --config Release --target PACKAGE

The package contains bin\AngelScript.dll, public headers under include\, and project documentation under share\doc\CKAngelScript\.

Validate Locally

Run the repeatable local workflow:

tools\Validate-Local.ps1 -BuildDir build -Configuration Release

This configures and builds the plugin. Game- or application-specific launch automation belongs in the corresponding host integration project.

First Runtime Script

Runtime scripts live under a Scripts directory. A directory module uses script.as as the manifest.

Data\Scripts\hello.runtime\script.as
Data\Scripts\hello.runtime\runtime.as

script.as:

[script id="hello.runtime" name="Hello Runtime" version="1.0.0" entry="runtime.as"]
[script.messages topics="hello.ping"]

runtime.as:

void OnLoad(const ScriptContext &in ctx) {
    print("Loaded " + ctx.Id());
}

void Update(const ScriptContext &in ctx) {
    if (ctx.FrameIndex() == 1) {
        dictionary payload;
        payload["source"] = ctx.Id();
        Message::Publish(ctx, "hello.ready", payload);
    }
}

void OnMessage(const ScriptMessage &in msg, const ScriptContext &in ctx) {
    print("message " + msg.Topic());
}

Validate before launching the host:

tools\Validate-ScriptEntries.ps1 -ScriptRoot C:\Path\To\Game\Data

First Component

Add the AngelScript Component Building Block to a behavior graph. Give it a class name and script source:

class Spinner {
    [param type="float" default="0.02"]
    float Speed;

    void Update(const CKBehaviorContext &in ctx) {
        Entity3DRef@ target = Scene::FindEntity3D(ctx, "Ball", 0, true);
        if (target is null || !target.valid) {
            return;
        }

        CK3dEntity@ entity = target.Entity3D();
        if (entity !is null) {
            entity.Rotate(0.0f, 1.0f, 0.0f, Speed);
        }
    }
}

The [param] metadata creates a Virtools input parameter and injects its value into Speed.

Next Steps