Experiment: Source

An open-source platform for creating Source Engine mods with Lua, with compatibility for Garry's Mod scripts and addons.

Warning

This project is still in early development and is not yet ready for use. Additionally it is currently being worked on on-and-off, by a single developer.

Given the current state of the project: please be aware that you will likely encounter bugs and security issues, documentation may be incomplete or outdated, and features may be missing or incomplete. Furthermore your contributions and issue reports are very welcome, but they may not be responded to, reviewed or merged in a timely manner.

If you are interested in contributing, please feel free to open an issue and/or create a pull request. If you are not sure where to start or what to do, start a discussion in the Discussions tab.

🐣 Origin

Initially this repository mainly worked towards creating a Source Engine mod called "Experiment". It was intended as a multiplayer mod, based on the Source SDK 2013, running the Garry's Mod gamemode 'Experiment Redux'. » 🕹 Read more about Experiment in the Garry's Mod gamemode repository

However during development an alternative idea that arose: that Experiment could be used as a platform for creating Source Engine mods. This would allow developers to create their own mods based on the Source SDK 2013, but without writing C++. Instead mods could be created with Lua scripting and other features not present in the original Source Engine SDK. » 💡 Read more about Experiment as a platform in the Developer Portal

Finally, super special thanks to those who contributed to the Half-Life 2: Sandbox project! That repository served as a great source of code and inspiration to get 'Experiment: Source' off the ground.

✨ Features

• Lua Scripting: Write your mod in Lua, a powerful and easy-to-learn scripting language.
• Garry's Mod compatibility: Use Garry's Mod addons, gamemodes, scripts and binary modules in your mod.
• Game Content mounting: Mount content from other Source Engine games, like Half-Life 2, Counter-Strike: Source and more.

» Visit the Developer Portal for our full Goals & Roadmap.

📸 Gallery

View media

   

spawnmenu.mp4

🚀 Getting started

Please keep in mind that this project has been developed on Windows. It is possible that instructions may not work on other operating systems.

Requirements

• Source SDK 2013 Multiplayer Base (Installed through Steam)
• Visual Studio 2022 (or newer)
• Visual Studio 2013 (for the Source SDK 2013 solution) (microsoft.com, archive.org mirror, alternative mirror)
• Perl (e.g. Strawberry Perl)
• (Not required, but recommended) Git Bash for running bash scripts

» See the Source SDK 2013 documentation for more information.

Step-by-step

After (forking and) cloning the repository, follow these steps to setup the project:

1. Go into the src/ directory and generate the Visual Studio solution.

   cd src
   creategameprojects.bat

2. Build the shaders

   cd src
   ./buildshaders.sh

3. Copy the .env.example file to .env.

   cp .env.example .env

4. Fill the .env file with the described values

5. Next run the setupprojects.sh script to modify the Visual Studio project files and solution.

   cd src
   ./setupprojects.sh --init

   This script will:

   • Set up debugging in the Visual Studio Client (Experiment) project file
   • Enforces the correct project dependencies of all projects.
   • The --init flag will cause all Source SDK 2013 executables and neccessary files to be copied to game/, so that the game can be run as a standalone mod.

6. Open the created experiment.sln solution in Visual Studio 2022 (or newer).

Warning

Despite being able to build within Visual Studio 2022, the Source SDK 2013 solution requires Visual Studio 2013 (and/or its build tools) to be installed.

7. To setup the game mod directory, run this in the root directory of the repository:

   ./tools/setup-game.sh

   This setups up a settings.scr file based on an example that is in this repository.

8. Make sure Steam is running and start the game through the Client (Experiment) project.

9. If you want to try out Garry's Mod sandbox:

   • Make sure that Garry's Mod is installed through Steam
   • Start Experiment
   • Mount Garry's Mod through the main menu
   • Restart Experiment
   • When starting a new server, select the sandbox gamemode

Note

Some of the instructions above may (no longer) be necessary, but they are included since at some point during development they were found to be necessary.

📚 Documentation

We build and present the Experiment Developer Documentation using mkdocs-material.

• 📕 View Lua API Documentation
• 👓 Read our conventions

Building the documentation

Requirements

• Python 3.8 or newer

Installation

1. Install the required Python packages.

   pip install -r requirements.txt

2. Start the development server.

   mkdocs serve --dirty

   Compiling the documentation will take a couple minutes.

   The --dirty flag is used to make live-reloading only rebuild the changed files, rather than the entire site. This is useful for faster development (see also issue #3695 in the mkdocs repo).

3. Open the documentation in your browser @ [http://localhost:8000/experiment-source/]

🏸 Extras

Updating from Source SDK 2013

1. Switch to the master branch.

   git checkout master

2. Ensure that the upstream repository is added as a remote.

   git remote add upstream https://github.com/ValveSoftware/source-sdk-2013
   git remote set-url --push upstream DISABLE

3. Fetch the latest changes from the upstream repository.

   git fetch upstream

4. Merge the changes from the upstream repository into the master branch.

   git merge upstream/master

5. Resolve any merge conflicts, if necessary.

6. Push the changes to this forked repository.

   git push origin master

7. Switch to the experiment-main branch.

   git checkout experiment-main

8. Merge the changes from the master branch into the experiment-main branch.

   git merge master

Attaching the debugger manually

This should not be necessary if you've run the setupprojects.sh script.

More instructions can be found here: check the official docs and use values like this:

Setup the debugger with the following values:

• Command: C:\Program Files %28x86%29\Steam\steamapps\common\Source SDK Base 2013 Multiplayer\hl2.exe
• Command Arguments: -allowdebug -dev -sw -game "C:\Program Files (x86)\Steam\steamapps\sourcemods\experiment"
• Working Directory: C:\Program Files %28x86%29\Steam\steamapps\common\Source SDK Base 2013 Multiplayer