View source for Engine tools

{{LanguageBar}}

[[File:Particles asw unadorned.jpg|thumb|The [[Particle Editor]].]]
[[File:SFM snap UI.png|thumb|The [[Source Filmmaker]].]]
[[File:MaterialEditor.jpg|thumb|The [[Material Editor]].]]
[[File:CommentaryEditor.jpg|thumb|The [[Commentary Editor]].]]
[[File:Actbusyeditor.jpg|thumb|The [[ActBusy Script Editor]].]]
[[File:EntityPlacementToolscreenshot.jpg|thumb|The [[Entity Placement Tool]].]]
[[File:Deferred_phong_ref.png|thumb|The [[Light editor]] (third-party).]]
[[File:Shadereditor_tutorial_assign.png|thumb|The third-party [[Source shader editor]] (third-party).]]
'''Engine tools''' are in-game {{Source|4}} tools that are used to aid in development, ease repetitive tasks, and otherwise manipulate the game in real-time.

== List of tools ==
Official tools created by {{Valve|4}}:
* [[Particle Editor]]
* [[Material Editor]]
* [[ActBusy Script Editor]]
* [[Entity Placement Tool]] {{only|{{l4d2}}}}
* [[Commentary Editor]]
* [[Foundry]]
* {{sfm|4}}
Third-party tools:
* [[Light editor]]
* [[Source shader editor]]
* {{directorscut|4}}
Additionally, see the [[:Category:Third Party Engine Tools|Third Party Engine Tools]] category.

== Usage ==
To launch a game or mod in tools mode, run a [[command line|command]] like this:

 hl2.exe -game <mod path> -tools -nop4

Failure to specify <code>-nop4</code> may lead to the engine exiting silently. This is used to disable {{w|Perforce}} Helix (P4) integration, as most users do not have it installed.

When the game has loaded you will be presented with the first tool in the order as specified in <code>bin/enginetools.txt</code> {{since|{{l4d2}}}} or <code>bin/sdkenginetools.txt</code>.

Use {{key|F10}} to toggle between controlling the game and tool window {{not|{{sfm}}{{directorscut}}}}, and {{key|F11}} to toggle visibility of the tool window.

== Setting key bindings ==
Most tools provide a window to set key bindings, which can be opened with <code>Edit -> Key Bindings</code>. For tools that utilize [[Qt]], use <code>Help -> Keyboard Shortcuts</code> {{only|{{sfm}}{{directorscut}}}}.

[[File:KeyBindingsEditor.jpg]] [[File:KeyboardShortcutsSFM.png]]

{{bug|tested={{sfm}}|Sometimes setting multiple actions to the same key binding may result in only one of the actions functioning.}}

Each key binding is only active while the tool window is being controlled. All bindings in the "General" and "Global" categories are accessible without being tabbed into an individual window, while other tabs are exclusive to the window they are named after.

=== Loading new tools ===
{{warning|You are likely to encounter instability if you try to mix engine branches.}}

In {{l4d2|4}} and later, you can manage tool availability with the <code>toolload</code> and <code>toolunload</code> console commands or by editing the engine's <code>bin/enginetools.txt</code> file. There is a GUI window for this too, but it's currently broken.

In earlier engine branches, tools must be specified in <code>bin/sdkenginetools.txt</code> in order to load:
<syntaxhighlight lang=d>
"enginetools"
{
	"library"	"tools/commedit.dll"
	"library"	"tools/pet.dll"
	"library"	"tools/vmt.dll"
}
</syntaxhighlight>

For 64-bit engine builds, use <code>bin/x64/sdkenginetools.txt</code>. Due to a [[VPC]] script bug, 64-bit tool modules are placed in <code>bin/tools/x64</code> instead of <code>bin/x64/tools</code>. Therefore, loading 64-bit tools requires directory traversal:
<syntaxhighlight lang=d>
"enginetools"
{
	"library"	"../tools/x64/commedit.dll"
	"library"	"../tools/x64/pet.dll"
	"library"	"../tools/x64/vmt.dll"
}
</syntaxhighlight>

See the directory containing the tools for your engine branch to know which libraries may be added.

== Development ==
The SDK provides header files in {{Path|src\public\toolframework}} with which new editor tools can be written. Engine tools are usable throughout any mod that depends on the targeted SDK version, making it possible to load custom tools into others' mods.

Tool framework modules must expose an interface derived from <code>IToolDictionary</code> using <code>VTOOLDICTIONARY_INTERFACE_VERSION</code>. Tools provided by the dictionary are derived from <code>IToolSystem</code>.

=== Creating a custom tool ===
Follow these steps to create an example tool using the {{tf2branch|1|nt=0}} of {{src13mp|4}} (64-bit) and Visual Studio 2022. First, create the directory {{Path|src\tools\mycustomtool}}, and write a VPC script to {{Path|src\tools\mycustomtool\mycustomtool.vpc|icon=file}}:

<syntaxhighlight lang=d>
$Macro SRCDIR "..\.."
$Macro OUTBINNAME "mycustomtool"
$Macro OUTBINDIR "$SRCDIR\..\game\bin\tools"
$Include "$SRCDIR\vpc_scripts\source_dll_base.vpc"
$Project "My Custom Tool"
{
    $Folder "Source Files"
    {
		-$File "$SRCDIR\public\tier0\memoverride.cpp"
        $File "mycustomtool.cpp"
    }
}
</syntaxhighlight>

This VPC script must be included in {{Path|src\vpc_scripts\projects.vgc|icon=file}}:

<syntaxhighlight lang=d>
$Project "mycustomtool"
{
	"tools\mycustomtool\mycustomtool.vpc" [$WINDOWS]
}
</syntaxhighlight>

And a group must be defined containing this project in {{Path|src\vpc_scripts\groups.vgc|icon=file}}:

<syntaxhighlight lang=d>
$Group "mycustomtool"
{
	"mycustomtool"
}
</syntaxhighlight>

The {{Path|src\tools\mycustomtool\mycustomtool.cpp|icon=file}} source file that was defined in the project VPC script should contain this code:

<syntaxhighlight lang=cpp>
// Absolute bare minimum example of a custom tool, ideally you should use headers and separate files for each class!!!
#include "toolframework/itoolsystem.h"
#include "toolframework/itooldictionary.h"

class CMyCustomTool : public IToolSystem
{
public:
    CMyCustomTool() {}
    virtual const char* GetToolName() { return "My Custom Tool"; }
    virtual bool Init() { return true; }
    virtual void Shutdown() {}
    virtual bool ClientInit(CreateInterfaceFn clientFactory) { return true; }
    virtual void OnToolActivate() {}
    virtual void OnToolDeactivate() {}
    virtual bool ServerInit(CreateInterfaceFn serverFactory) { return true; }
    virtual void ServerShutdown() {}
    virtual void ClientShutdown() {}
    virtual bool CanQuit() { return true; }
    virtual void PostMessage(HTOOLHANDLE hEntity, KeyValues* message) {}
    virtual void Think(bool finalTick) {}
    virtual void ServerLevelInitPreEntity() {}
    virtual void ServerLevelInitPostEntity() {}
    virtual void ServerLevelShutdownPreEntity() {}
    virtual void ServerLevelShutdownPostEntity() {}
    virtual void ServerFrameUpdatePreEntityThink() {}
    virtual void ServerFrameUpdatePostEntityThink() {}
    virtual void ServerPreClientUpdate() {}
    virtual void ServerPreSetupVisibility() {}
    virtual const char* GetEntityData(const char* pActualEntityData) { return pActualEntityData; }
    virtual void ClientLevelInitPreEntity() {}
    virtual void ClientLevelInitPostEntity() {}
    virtual void ClientLevelShutdownPreEntity() {}
    virtual void ClientLevelShutdownPostEntity() {}
    virtual void ClientPreRender() {}
    virtual void ClientPostRender() {}
    virtual void AdjustEngineViewport(int& x, int& y, int& width, int& height) {}
    virtual bool SetupEngineView(Vector& origin, QAngle& angles, float& fov) { return false; }
    virtual bool SetupAudioState(AudioState_t& audioState) { return false; }
    virtual bool ShouldGameRenderView() { return true; }
    virtual bool IsThirdPersonCamera() { return false; }
    virtual bool IsToolRecording() { return false; }
    virtual IMaterialProxy* LookupProxy(const char* proxyName) { return nullptr; }
    virtual bool TrapKey(ButtonCode_t key, bool down) { return false; }
    virtual bool GetSoundSpatialization(int iUserData, int guid, SpatializationInfo_t& info) { return false; }
    virtual void RenderFrameBegin() {}
    virtual void RenderFrameEnd() {}
    virtual void HostRunFrameBegin() {}
    virtual void HostRunFrameEnd() {}
    virtual void VGui_PreRender(int paintMode) {}
    virtual void VGui_PostRender(int paintMode) {}
    virtual void VGui_PreSimulate() {}
    virtual void VGui_PostSimulate() {}
};

class CToolDictionary : public IToolDictionary
{
public:
    // Here is where you should connect new interfaces in the future:
    virtual bool Connect(CreateInterfaceFn factory) { return true; }
    virtual void Disconnect() {}
    virtual void* QueryInterface(const char* szInterfaceName) { return Sys_LoadModule(szInterfaceName, SYS_NOFLAGS); }
    virtual InitReturnVal_t Init() { return INIT_OK; }
    virtual void Shutdown() { delete m_pMyCustomTool; }
    virtual void CreateTools() { m_pMyCustomTool = new CMyCustomTool(); }
    virtual int GetToolCount() const { return 1; }
    virtual IToolSystem* GetTool(int index) { return m_pMyCustomTool; }
private:
    CMyCustomTool* m_pMyCustomTool;
};
static CToolDictionary g_ToolDictionary;
EXPOSE_SINGLE_INTERFACE_GLOBALVAR(CToolDictionary, IToolDictionary, VTOOLDICTIONARY_INTERFACE_VERSION, g_ToolDictionary);
</syntaxhighlight>

To create the solution in order to build, add <code>+mycustomtool</code> to {{Path|src\createallprojects.bat|icon=exe}}:

<syntaxhighlight lang=bat>
devtools\bin\vpc.exe /hl2mp /tf /define:SOURCESDK +everything +mycustomtool /mksln everything.sln
</syntaxhighlight>

Afterwards, run it and open the {{Path|src\everything.sln|icon=file}} solution with Visual Studio 2022. Once loaded, build the project titled "My Custom Tool".

Building the project will produce {{Path|game\bin\tools\x64\mycustomtool.dll|icon=file}}, which would need to be copied to {{Path|Source SDK Base 2013 Multiplayer\bin\tools\x64}} and defined in {{Path|Source SDK Base 2013 Multiplayer\bin\x64\sdkenginetools.txt|icon=file}}:

<syntaxhighlight lang=d>
"enginetools"
{
	"library"	"../tools/x64/commedit.dll"
	"library"	"../tools/x64/pet.dll"
	"library"	"../tools/x64/vmt.dll"
	"library"	"../tools/x64/mycustomtool.dll"
}
</syntaxhighlight>

Then, run the SDK with the launch parameters <code>-game <mod path> -tools -nop4</code> to run with tools enabled. Once in-game, "My Custom Tool" will now be accessible in the <code>Tools</code> menu from other tools, where activating it will simply just return you to the game without any way to switch back to other tools.

This is because custom engine tools are responsible for implementing their own UI code, and the example provides does not provide any UI. The tool switching behavior may be defined using <code>enginetools->SwitchToTool(int index)</code>, although doing so would require connecting the <code>enginetools</code> interface beforehand.

[[Category:Modding]]
[[Category:Official Source Tools]]
[[Category:Source]]