Agent integration guide

{
  "scopedRegistries": [
    {
      "name": "PIO",
      "url": "https://packages.pioneeroptimisation.com",
      "scopes": [
        "com.pioneeroptimisation"
      ]
    }
  ],
  "dependencies": {
    "com.cysharp.unitask": "https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#2.5.11",
    "com.pioneeroptimisation.sdk": "0.3.6"
  }
}

using System;
using System.Collections.Generic;
using PIO;
using UnityEngine;

// The PIO class shares its name with the PIO namespace, so a script outside
// the PIO namespace must bring the statics in explicitly.
using static PIO.PIO;

/// <summary>
/// The agent integration guide's bootstrap, verbatim: attach to a GameObject
/// named PIO in the first loaded scene, fill the credentials, press Play.
/// Lives in the global namespace on purpose, so it compiles exactly as
/// pasted into a fresh project.
/// </summary>
public class PioBootstrap : MonoBehaviour
{
    [SerializeField] string apiKey = "";
    [SerializeField] string accountId = "";
    [SerializeField] string projectId = "";

    async void Start()
    {
        // Headless setups export credentials instead of typing them into the
        // Inspector; a filled Inspector field always wins, and nothing writes
        // a key into a committed scene or asset.
        apiKey = string.IsNullOrEmpty(apiKey) ? Environment.GetEnvironmentVariable("PIO_API_KEY") ?? "" : apiKey;
        accountId = string.IsNullOrEmpty(accountId) ? Environment.GetEnvironmentVariable("PIO_ACCOUNT_ID") ?? "" : accountId;
        projectId = string.IsNullOrEmpty(projectId) ? Environment.GetEnvironmentVariable("PIO_PROJECT_ID") ?? "" : projectId;

        // Surface every SDK error as a console line while integrating.
        OnError += e =>
            Debug.LogWarning($"[PIO] {e.Severity} {e.Code}: {e.Message}");

        var config = new PioConfig
        {
            ApiKey = apiKey,
            AccountId = accountId,
            ProjectId = projectId,
            Actions = new Dictionary<string, ActionDef>
            {
                // The fallback serves whenever the backend cannot answer.
                ["Tutorial"] = new ActionDef { FallbackAction = "Short" },
            },
        };

        await Init(config);
        if (this == null) return; // Destroyed during the await: stop.
        if (!IsReady)
        {
            Debug.Log($"PIO init failed: {State}");
            return;
        }

        // Ask at the decision point and apply the returned action. A null
        // Action marks the baseline control group; a null result means
        // tracking is disabled; both show your control experience.
        var decision = await GetDecision("Tutorial");
        if (this == null) return;
        ApplyTutorialLength(decision?.Action ?? "Short");

        // A valued event: the value feeds reward derivation.
        TrackEvent("level_complete", 1.0);

        // A bare occurrence, no value.
        TrackEvent("tutorial_complete");
    }

    void ApplyTutorialLength(string action) =>
        Debug.Log($"Tutorial length: {action}");
}

using System.Collections.Generic;
using UnityEditor;
using UnityEditor.SceneManagement;
using UnityEngine;

public static class PioSetup
{
    public static void Run()
    {
        System.IO.Directory.CreateDirectory("Assets/Scenes");
        var scene = EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
        var go = new GameObject("PIO");
        go.AddComponent<PioBootstrap>();
        EditorSceneManager.SaveScene(scene, "Assets/Scenes/Main.unity");
        var scenes = new List<EditorBuildSettingsScene>(EditorBuildSettings.scenes);
        if (!scenes.Exists(sc => sc.path == "Assets/Scenes/Main.unity"))
        {
            scenes.Insert(0, new EditorBuildSettingsScene("Assets/Scenes/Main.unity", true));
        }
        EditorBuildSettings.scenes = scenes.ToArray();
    }
}

{
  "name": "PIO.Samples",
  "rootNamespace": "PIO.Samples",
  "references": [
    "PIO.Runtime"
  ],
  "includePlatforms": [],
  "excludePlatforms": [],
  "allowUnsafeCode": false,
  "overrideReferences": false,
  "precompiledReferences": [],
  "autoReferenced": true,
  "defineConstraints": [],
  "versionDefines": [],
  "noEngineReferences": false
}

{
  "name": "PIO.Samples.Tests.PlayMode",
  "references": ["PIO.Samples", "PIO.Runtime", "UnityEngine.TestRunner", "UnityEditor.TestRunner"],
  "overrideReferences": true,
  "precompiledReferences": ["nunit.framework.dll"],
  "defineConstraints": ["UNITY_INCLUDE_TESTS"]
}

using System.Collections;
using NUnit.Framework;
using UnityEngine;
using UnityEngine.SceneManagement;
using UnityEngine.TestTools;
using static PIO.PIO;

/// <summary>
/// Drives the guide's bootstrap end to end: loads the scene the setup script
/// built, lets PioBootstrap run Init, a decision, and both events, then waits
/// one flush interval so the queue ships before the test ends. Export the
/// three PIO_* variables before running it headless. Delete the test assembly
/// after verification if the project does not keep tests.
/// </summary>
public class PioIntegrationPlayModeTests
{
    [UnityTest]
    public IEnumerator BootstrapInitialisesAndShipsEvents()
    {
        yield return SceneManager.LoadSceneAsync("Main", LoadSceneMode.Single);

        var pio = GameObject.Find("PIO");
        Assert.IsNotNull(pio, "PIO GameObject missing from the Main scene");
        Assert.IsNotNull(pio.GetComponent<PioBootstrap>(), "PioBootstrap not attached");

        // Start() is async void, so the scene load returns before init runs.
        // Wait for readiness first, or the flush timer below starts before
        // any event has been tracked.
        var deadline = Time.realtimeSinceStartup + 30f;
        while (!IsReady && Time.realtimeSinceStartup < deadline)
        {
            yield return null;
        }
        Assert.IsTrue(IsReady, $"PIO not ready within 30 seconds (state: {State})");

        // A few seconds for the decision and both events to be tracked, then
        // one flush interval (30 seconds by default) plus a little slack, so
        // the tracked events leave the queue before the test ends.
        yield return new WaitForSeconds(5f);
        yield return new WaitForSeconds(31f);
    }
}