Difference between revisions of "Sample Plugins (Metamod:Source)"

From AlliedModders Wiki
Jump to: navigation, search
m
m
Line 1: Line 1:
This guide briefly explains about and how to compile the sample plugins for Metamod:Source.
+
Metamod:Source comes with two sample plugins: <tt>stub</tt> and <tt>sample</tt>.  This article is a brief overview of how to read and compile them.  They are intended as a baseline for developing your own plugins.
  
On Visual Studio 8.0, each plugin contains a "Release" and "Debug" build configuration for both Orange Box and the original engine.
+
Metamod:Source is a C++ environment, but this is not a C++ tutorial. You should have sufficient knowledge of computer organization (memory, pointers, addressing) and intermediate experience with C++.  Most importantly, you should be willing to dive into header files to research API definitions (which is necessary for the HL2SDK regardless).
  
When using GCC, there are two separate makefiles for each engineFor example:
+
=Introduction=
<cpp>make -f Makefile.ep2 debug</cpp>
+
Before you begin, you should set up your [[Metamod:Source Environment]]If you fail to complete this step, it is unlikely much else in this article will work for you.
  
Would build the Orange Box version of that plugin.
+
The two sample plugins provided are:
 +
*<tt>stub_mm</tt> - Bare-bones plugin that does almost nothing.
 +
*<tt>sample_mm</tt> - More filling example plugin which implements a few things that Valve's serverplugin_sample does, such as hooking functions, creating ConVars, console commands, and showing dialog boxes.
  
=Sample Plugins=
 
==stub_mm==
 
This plugin is a bare-minimum example of what you need to build a [[Metamod:Source]] plugin. It implements the ISmmPlugin class, exposes it as a DLL, and nothing more. As a single example, it also hooks ServerActivate in IServerGameDLL. "Stub" was designed such that a developer could open it and quickly modify it to begin a plugin.
 
  
*stub_mm.cpp - Main plugin file and implementation
+
=The Engine Divide=
*stub_mm.h - Main plugin header
+
The Orange Box and Episode 1 engines are not compatible, and thus there is a division:
 +
*Metamod:Source 1.4/Episode 1
 +
*Metamod:Source 1.6/Orange Box
  
==sample_mm==
+
Unfortunately, there is a "lag period" where not all games have moved to the new engine.  It is likely that this lag period will continue for at least another twelve months (this writing is as of February 2008).  As such, we are writing all of our plugin code such that it compiles against both platforms'''It is your choice whether to do this as well.''' As the usage of Metamod:Source 1.4 and the original engine decays, we will begin removing the legacy cruft from the sample plugins.
The sample plugin re-implements Valve's serverplugin_empty sample.  It contains demonstrations of hooking events, creating cvars/commands, and displaying dialogs to clients.
 
  
*sample_mm.cpp - Main plugin file and implementation
 
*sample_mm.h - Main plugin header
 
*engine_wrappers.h - Wrapper functions for abstracting Half-Life engine versions.
 
  
=Where to Get=
+
=Compiling=
You can find the source code to the sample plugins in either the source code package or [http://svn.alliedmods.net/viewvc.cgi/?root=sourcemm SVN].  For example, using <tt>trunk</tt>, <tt>trunk/sample_mm</tt>.
 
  
=Compiling=
 
 
==Windows==
 
==Windows==
These plugins have been compiled and tested with Microsoft Visual Studio 8.0 (.NET 2005)No earlier version is supported. Before you compile, you must have these directories in your include options. To set these, go to Tools, Options, Projects, VC++ Directories.
+
Both plugins have a Visual Studio 2005 project file in their <tt>msvc8</tt> foldersEach plugin has four build modes:
 +
*<tt>Release - Orange Box</tt> - Release mode, Orange Box, MM:S 1.6
 +
*<tt>Debug - Orange Box</tt> - Debug mode, Orange Box, MM:S 1.6
 +
*<tt>Release - Original</tt> - Release mode, Original/Episode1, MM:S 1.4
 +
*<tt>Debug - Original</tt> - Debug mode, Original/Episode1, MM:S 1.4
  
*From the Include Files menu, add these HL2SDK paths:
+
There exists normal "Release" and "Debug" build modes -- you should not use them, as they are not configured.
**public
 
**public/dlls
 
**public/engine
 
**public/tier0
 
**public/tier1
 
**public/vstdlib
 
**tier1
 
*From the Library Files menu, add these HL2SDK paths:
 
**lib/public
 
*From the Include Files menu, add these SourceMM paths:
 
**sourcemm
 
**sourcemm/sourcehook
 
**sourcemm/sourcemm
 
  
You can then open the .vcproj project file. Go to Build, Set Active Configuration, and select Release. You can then select Build from the Build menu, which will produce a .dll file in the Release folder in the project folder.
+
==Linux==
 +
On Linux, you cannot simply type "make" in the folder containing the <tt>Makefile</tt>. You must specify a combination of parameters:
 +
*<tt>ENGINE</tt> - Required. Must be either "orangebox" or "original".
 +
*<tt>DEBUG</tt> - Optional. Can be empty (Release mode) or "true" (Debug mode).
  
==Linux==
+
Binaries and object files will be written to one of the following folders:
To build on Linux, you must have a copy of Source Dedicated Server installed. Open the project Makefile and edit the following lines at the top:
+
*<tt>Release.orangebox</tt>
 +
*<tt>Debug.orangebox</tt>
 +
*<tt>Release.original</tt>
 +
*<tt>Debug.original</tt>
  
*SRCDS - Location of main srcds installation
+
Examples of building one of the example plugins:
*SMM_ROOT - Location of folder containing sourcemm and sourcehook
+
<pre>
*HL2SDK - Location of HL2SDK
+
#MM:S 1.4/Episode 1, debug mode
 +
make DEBUG=true ENGINE=original
 +
#MM:S 1.6/Orange Box, release mode
 +
make ENGINE=orangebox
 +
#Cleaning the MM:S 1.4 build
 +
make clean ENGINE=original
 +
</pre>
  
Once done, you can just type "make -f Makefile.epX" to run the build scripts, where X corresponds to the Half-Life 2 engine version (episode 1 is the older engine, and episode 2 is the Orange Box engine).  The binary will appear in ./Release/ for normal builds, or ./Debug/ for debug builds.
+
'''Note''' that you may need to edit the folder locations at the top of the Makefile, in case you set up your paths differently.
  
 
[[Category:Metamod:Source Development]]
 
[[Category:Metamod:Source Development]]

Revision as of 22:28, 17 February 2008

Metamod:Source comes with two sample plugins: stub and sample. This article is a brief overview of how to read and compile them. They are intended as a baseline for developing your own plugins.

Metamod:Source is a C++ environment, but this is not a C++ tutorial. You should have sufficient knowledge of computer organization (memory, pointers, addressing) and intermediate experience with C++. Most importantly, you should be willing to dive into header files to research API definitions (which is necessary for the HL2SDK regardless).

Introduction

Before you begin, you should set up your Metamod:Source Environment. If you fail to complete this step, it is unlikely much else in this article will work for you.

The two sample plugins provided are:

  • stub_mm - Bare-bones plugin that does almost nothing.
  • sample_mm - More filling example plugin which implements a few things that Valve's serverplugin_sample does, such as hooking functions, creating ConVars, console commands, and showing dialog boxes.


The Engine Divide

The Orange Box and Episode 1 engines are not compatible, and thus there is a division:

  • Metamod:Source 1.4/Episode 1
  • Metamod:Source 1.6/Orange Box

Unfortunately, there is a "lag period" where not all games have moved to the new engine. It is likely that this lag period will continue for at least another twelve months (this writing is as of February 2008). As such, we are writing all of our plugin code such that it compiles against both platforms. It is your choice whether to do this as well. As the usage of Metamod:Source 1.4 and the original engine decays, we will begin removing the legacy cruft from the sample plugins.


Compiling

Windows

Both plugins have a Visual Studio 2005 project file in their msvc8 folders. Each plugin has four build modes:

  • Release - Orange Box - Release mode, Orange Box, MM:S 1.6
  • Debug - Orange Box - Debug mode, Orange Box, MM:S 1.6
  • Release - Original - Release mode, Original/Episode1, MM:S 1.4
  • Debug - Original - Debug mode, Original/Episode1, MM:S 1.4

There exists normal "Release" and "Debug" build modes -- you should not use them, as they are not configured.

Linux

On Linux, you cannot simply type "make" in the folder containing the Makefile. You must specify a combination of parameters:

  • ENGINE - Required. Must be either "orangebox" or "original".
  • DEBUG - Optional. Can be empty (Release mode) or "true" (Debug mode).

Binaries and object files will be written to one of the following folders:

  • Release.orangebox
  • Debug.orangebox
  • Release.original
  • Debug.original

Examples of building one of the example plugins:

#MM:S 1.4/Episode 1, debug mode
make DEBUG=true ENGINE=original
#MM:S 1.6/Orange Box, release mode
make ENGINE=orangebox
#Cleaning the MM:S 1.4 build
make clean ENGINE=original

Note that you may need to edit the folder locations at the top of the Makefile, in case you set up your paths differently.