A Memory-Driven Action Selection Framework for Scalable Ambient NPC Behavior

What's in the zip

The zip contains the complete framework source code. src/ contains the framework implementation, include/ contains the public C API header files, and tests/ contains the unit tests. The build system is configured through CMakeLists.txt and CMakePresets.json, with dependencies declared in vcpkg.json. A Doxyfile is included for generating API documentation. The vcpkg dependency manager is not included in this zip as it is managed as a git submodule. To build the project from source, clone the GitHub repository instead.

Building from the GitHub repository (recommended)

Cloning the repository handles the vcpkg dependency manager automatically through git submodules. This is the recommended approach for building from source.

1. Clone the repository:

   git clone https://github.com/EricBL3/ambient-behavior-core-framework.git
   cd AmbientCoreFramework

2. macOS only — install additional build tools:

   # Install Homebrew if needed
   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
   # Install required tools
   brew install pkg-config
   
   # Ensure Xcode Command Line Tools are installed
   xcode-select --install

3. Bootstrap vcpkg:

   git submodule update --init --recursive
   cd vcpkg
   
   # Windows
   .\bootstrap-vcpkg.bat
   
   # macOS / Linux
   ./bootstrap-vcpkg.sh
   
   cd ..

4. Install dependencies:

   cd vcpkg
   ./vcpkg install
   cd ..

5. Configure for your platform:

   # Windows
   cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows
   
   # macOS (Intel)
   cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-osx
   
   # macOS (Apple Silicon)
   cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-osx
   
   # Linux
   cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-linux

6. Build and run tests:

   cmake --build build --config Release
   cd build
   ctest --config Release
   cd ..

Optional: generate Doxygen documentation

1. Install Doxygen.
2. Run doxygen Doxyfile in the project root.
3. Open docs/doxygen/html/index.html.

About the source zip download

The downloadable zip is provided for reading and inspecting the source code. Because vcpkg is managed as a git submodule, the zip does not include the full vcpkg installation needed to build. To compile the project, clone from the GitHub repository using the steps above.

What's in the zip

The zip contains the full Unity 6 project. The relevant contents for review within the Assets/ folder are organized as follows: Scripts/AmbientCharacterFrameworkIntegration/ contains the C# wrapper layer that bridges the C++ framework with Unity, while the remaining folders in Scripts/ contain demo-specific code. Plugins/ contains the pre-built framework DLL binaries. AmbientBehaviorFrameworkConfig/ contains the JSON configuration files that define NPC states, actions, sequences, and entity configurations (see Appendix A of the project report for documentation of this format). Scenes/ contains MainDemo and PerformanceDemo. The remaining folders (Animations/, Animators/, Audio/, Prefabs/, and PolygonAncientEmpire/) contain the demo's art assets, animations, and prefabs.

Steps

1. Extract the zip to a location of your choice.
2. Open Unity Hub and click Add to add the extracted project folder.
3. Open the project with Unity 6. On first open, Unity will regenerate its asset cache, which may take a few minutes.
4. In the Project window, navigate to Assets/Scenes/ and open MainDemo.unity.

5. Press Play. Wait a few seconds for the framework to initialize. Once ready, NPCs will begin moving around the environment and selecting actions autonomously.

6. You can move the player character using WASD keys and move the mouse to look around. You can also press E to make the player shout. Nearby NPCs will react to the shout through the interruption mechanism described in the project report.

Performance demo

The Assets/Scenes/PerformanceDemo.unity scene is the environment used for the performance evaluation described in Chapter 6 of the project report. It can be opened and run using the same steps above.

Configurable settings

Once the demo is running successfully, framework settings such as the character batch size can be adjusted. See Chapter 5 of the project report for how these settings are configured and what they control.

Pre-built framework binary

This project includes the pre-built framework binary. No separate download is needed to run the demo.

What's in the zip

The zip contains the full Unreal Engine 5.7 project. The relevant contents for review are organized as follows: Source/AmbientBehaviorDemo/AmbientBehaviorFramework/ contains the C++ wrapper layer that bridges the framework with Unreal Engine, while the remaining files in Source/AmbientBehaviorDemo/ contain demo-specific code. ThirdParty/AmbientCoreFramework/ contains the pre-built framework DLL binaries. Content/AmbientBehaviorFrameworkConfig/ contains the JSON configuration files that define NPC states, actions, sequences, and entity configurations (see Appendix A of the project report for documentation of this format). The demo level is located at Content/DemoScene.umap. Binaries/ contains the compiled game module, and Config/ contains project settings.

Steps

1. Extract the zip to a location of your choice.
2. Double-click AmbientBehaviorDemo.uproject to open the project in Unreal Engine 5.7.
3. If prompted to rebuild modules, select Yes. On first open, Unreal will compile shaders, which may take several minutes.
4. In the Content Browser, navigate to Content/ and open DemoScene.

5. In the toolbar, change the play mode from the dropdown next to the Play button. Select Standalone Game or New Editor Window to avoid the known editor freeze issue (see Prerequisites).
6. Click Play. Wait a few seconds for the framework to initialize. Once ready, NPCs will begin moving around the dance club or dancing in place. You can move around using WASD keys. Click Esc to close the running demo window.

Configurable settings

Once the demo is running successfully, framework settings such as the character batch size can be adjusted. See Chapter 5 of the project report for how these settings are configured and what they control.

Pre-built framework binary

This project includes the pre-built framework binary. No separate download is needed to run the demo.