CultSim comes from Culture and Simulation and not “Cult” as in Worship, although both Cult and Culture come from the same Etymology of Cultivate (Cultus in Latin).
- Leon Cinquemani
- Tomas Himberg Berger
- Carl Findahl
CultSim is a social simulation framework in the Agent-Based Modelling family, with a focus on performance, high-quality visualizations, and a flexible scripting environment.
It is intended as an easily extendable platform, on which complex simulations concerning the interactions between agents can be developed by researchers and developers alike. The finished simulations should be usable by non-developers as well if they are interested in observing the interactions between agents. Once simulations have been run, the collected data will be available to the user for further analysis in a program of their choice.
The Lua scripting language is embedded to provide users with the ability to implement their own scenarios, agents, and systems that govern their actions and decision making, striving for users to be able to customize nearly 100% of what makes up a simulation. Lua is a fast and lightweight language designed to be embedded in other programs and is relatively quick to learn. Using the Lua API in CultSim, developers can modify existing simulations, or create new ones!
You have two options when installing CultSim, you can download the binary that allows for Lua API, and normal use of the program. However, if you feel like CultSim is limiting you in any way, or there are some weird behaviors, you might want to build it from the source. If you do add more features or fix some bugs, we would be happy if you created push requests with the changes, so that we might include them in future versions of CultSim.
CultSim is compiled as a 64-bit binary and thus is only supported as such. If you wish for a 32-bit binary you need to compile it yourself, and you will need to fetch the 32-bit versions of the applicable libraries CultSim depends on.
For most users, unzipping the binary .zip file, running vc_redist.x64.exe, and making sure your graphics card is up to date should be all that is needed. However we have come across an issue with AMD graphics card needing some additional dependency, however, we have yet to isolate what that is, so post an issue if you can’t get it up and running.
On Linux, using a precompiled binary is currently not recommended as we can not guarantee that we are linking against the same version of the system libraries as on the distro we are building on. Therefore, you are advised to build from source, which should be relatively easy and not take too long.
To Compile CultSim from source CMake 3.15 is needed.
Before you start, ensure you have the following system libraries installed (on Ubuntu):
git, make, lua5.3, lua5.3-dev, libx11-dev, libxext-dev, clang, libphysfs-dev, libtbb-dev, wget, mesa-common-dev, libgl1-mesa-dev using apt. You might not need the mesa GL drivers if you are using an Nvidia or AMD GPU. These can be gotten using apt.
- Clone from Git
cdinto the root directory where you clonedmkdir buildcd buildCMake -G "Unix Makefiles" ../make -j#where the#is the number of threads you want to compile with
To run the program after building assuming you are coming right from the previous steps:
cd bachelor/sim./cultsim
- Clone from Git
- Generate the project files using CMake 3.15 or later
- If you are using the GUI version, browse to the source and build directories you want at the top of the interface. The source directory should be the folder you cloned, which contains the root
CMakeLists.txtfile. - Set any parameters you want in the main window.
- Then click
Configureat the bottom left of the UI and if you are using Visual Studio, choose a 64-bit version. - Once the configure stage has finished, click
Generate, and finallyOpen Project.
- If you are using the GUI version, browse to the source and build directories you want at the top of the interface. The source directory should be the folder you cloned, which contains the root
- Go to
(Folder you cloned the project into)/out/build/(the version you built, debug or release)/_deps/sdl2_external-build- Some CMake configurations do not automatically differentiate between Release/Debug, so you might find it directly in the build folder.
- Copy the
SDL2.dllfile - Go to
(Folder you cloned the project into)/out/build/(the version you built, debug or release)/bachelor/sim- See above for CMake config specific changes to this step
- Paste the
.dllfile here - repeat steps 3-6 for
physfs.dllin(Folder you cloned the project into)/out/build/(the version you built, debug or release)/_deps/physfs_external-build - Build the project
To get started writing scenarios with CultSim you need to use Lua and follow a basic format. You can look at the bundled basic needs scenario, or start from scratch on your own. Regardless, the documentation would be nice to have access to. If you’re building from source you can find the Lua scripting API documentation by enabling CULTSIM_BUILD_DOCS in the CMake configuration. This will build the documentation with Doxygen.
NOTE: Currently, the Lua documentation is incomplete and needs more work to be a complete source of information. The C++ documentation is almost complete though, so you can create simulations in C++ too if you want.
To run simulations in Cultsim all you need to do is to start the program and choose the “Load Scenario”-tab. From here, the user should see a list of all Scenarios they currently have in their \data\script\scenarios folder. They can choose a scenario by clicking one of these. Alternatively, they may also click the “load options”-tab in the “Load Scenario”-tab to change the random seed for the simulation, or to enable or disable visualization for the simulation.
From the main menu, they may also rebind the controls via the “Keybindings”-tab. Here they may add or remove key bindings from a different context, such as “Scenario Scene”, which would be the keybindings used during the simulation.
Finally, also on the main menu, is the option to exit the program entirely via the “Exit”-tab.
The default control scheme for CultSim is relatively small:
WASDorarrow keysto move the camera/viewport aroundQorScroll upto zoom the camera/viewport inEorScroll downto zoom the camera/viewport outMouse Button 1to select an entityFto follow a selected entity aroundPto open up a pause menuSpace Barto pause a simulation.to multiply the current simulation speed by 2,to divide the current simulation speed by 2F2to go to 2D modeF3to go to 3D modeEscapeto leave a menu or the program itself, depending on if you have a menu open or not
CultSim supports what some may find overly customizable keybindings, and it can be an issue to set-up custom ones. Though once the Keybinding UI is made sense of, you will find it to be very customizable.
The Keybinding file can be found on Windows in:
C:\Users\Your_User_Name\AppData\Roaming\g107\cultsim
And on Linux:
~/.local/share/cultsim
- Graphics API used for visualizing the simulations in CultSim in an efficient manner
- Used as a replacement to std::unordered_map as this implementation of a hash map is a lot faster, and the difference could not be neglected when measuring
- Used to create windows, and processing events from the operating system
- Our scripting language of choice
- Used internally for benchmarking Lua vs Python and other micro-benchmarks underway
- Flexible logging library used for error messages and general logging
- Used to create the Lua bindings for CultSim
- Immediate mode GUI library that is fast and easy to use. Used for our UI
- Plotting extension library for Dear ImGui
- Used as the entity-component-system for the project due to high performance and ease of use
- Virtual file system library to make our paths platform-agnostic and restrict write access
- A faster, smaller, and less predictable random number generator
- A task-oriented multithreading scheduling library to help us data-parallelize certain tasks in CultSim
- OpenGL Mathematics library for vector and matrix computations
- Fast and lightweight testing framework with a good CMake integration