Commit f89e9739 authored by NTAuthority's avatar NTAuthority

initial commit

parents
node_modules/
out/
# Your [DocPad](http://docpad.org) Project
## License
Copyright © 2014+ All rights reserved.
\ No newline at end of file
# DocPad Configuration File
# http://docpad.org/docs/config
# Define the DocPad Configuration
docpadConfig = {
collections:
pages: ->
@getCollection("html").findAllLive().on "add", (model) ->
model.setMetaDefaults({layout:"default", subsection:'IV'})
}
# Export the DocPad Configuration
module.exports = docpadConfig
\ No newline at end of file
{
"name": "no-skeleton.docpad",
"version": "0.1.0",
"description": "New DocPad project without using a skeleton",
"engines": {
"node": "0.10",
"npm": "1.3"
},
"dependencies": {
"docpad": "~6.69.0",
"docpad-plugin-eco": "~2.0.3",
"docpad-plugin-livereload": "~2.6.0",
"docpad-plugin-marked": "~2.2.1",
"docpad-plugin-less": "~2.4.1",
"docpad-plugin-menu": "~2.1.0",
"docpad-plugin-highlightjs": "~2.2.2"
},
"main": "node_modules/docpad/bin/docpad-server",
"scripts": {
"start": "node_modules/docpad/bin/docpad-server"
}
}
---
title: Admin Guide
---
CitizenMP:IV Administrator's Guide
==================================
This document will describe the basic process involved in setting up a server for the CitizenMP:IV multiplayer platform. This guide will not go into script/resource development; such details are better left to dedicated guides.
It is assumed that the reader is knowledgable of the platform they are intending on setting up a server on, and has access to a development environment as currently no precompiled binaries are available from official sources.
## Installation
The server can either be installed from binaries, or the [source code](http://tohjo.ez.lv/citidev/citizenmp-server) can be obtained and manually compiled. On Windows platforms, the .NET Framework 4.5 is the main supported installation method; on other platforms (and Windows NT 5.x), Mono 3.x should work just as well. Future versions of the CitizenMP server platform may or may not include standalone (i.e. independent of the .NET Framework/system Mono installation) builds for non-Windows platforms.
### From binaries
Binaries are not currently available. :(
### From source (Windows)
Visual Studio 2013 and a Git client are required.
1. Using a Git client, clone the [repository](http://tohjo.ez.lv/citidev/citizenmp-server.git):
```
git clone http://tohjo.ez.lv/citidev/citizenmp-server.git
git submodule update --init --recursive
```
2. Open the primary solution file (CitizenMP.Server.sln) in Visual Studio.
3. Make sure restoring of NuGet packages is enabled. This option can be found in Tools -> Options -> NuGet Package Manager -> General -> Allow NuGet to download missing packages.
4. Build the project (F6 or Build -> Build Solution).
5. Depending on the configuration selected (Release or Debug), you can find binaries (and the dependencies) in bin/Debug/ or bin/Release/. The data/ folder of the repository should be used as working directory for the server, which can for instance be done like the following:
```
C:\build\citizenmp-server\CitizenMP.Server> cd data
C:\build\citizenmp-server\CitizenMP.Server\data> ..\bin\Debug\CitizenMP.Server.exe
[...]
```
The server should now be running.
### From source (Ubuntu 14.04)
Ubuntu 14.04 is selected here as it includes modular prebuilt Mono 3.x packages -- other distributions may be able to compile Mono from source to do the same; we're not showing any of such details here.
1. Install the Mono platform dependencies.
```
# apt-get update
# apt-get install libmono-microsoft-build-tasks-v4.0-4.0-cil mono-devel
# mozroots --import --sync # to import TLS certificates for NuGet package import
```
2. Fetch the CitizenMP repository using Git (assuming it is installed).
```
$ git clone http://tohjo.ez.lv/citidev/citizenmp-server.git
$ cd citizenmp-server
$ git submodule update --init --recursive
$ export CITIZEN_SRC=$(pwd)
```
3. Restore NuGet packages and build the solution.
```
$ export EnableNuGetPackageRestore=true
$ mono .nuget/NuGet.exe restore -source "https://www.nuget.org/api/v2;http://nuget.citizen.re/nuget"
$ chmod +x ~/.local/share/NuGet/NuGet.exe # workaround for a nuget issue
$ mono .nuget/NuGet.exe restore -source "https://www.nuget.org/api/v2;http://nuget.citizen.re/nuget"
$ xbuild
```
4. Install the dependencies for the native Lua module.
```
# apt-get install cmake build-essential autoconf automake
```
5. Fetch the NLua Citizen fork [repository](http://tohjo.ez.lv/citidev/nlua) and build it.
```
$ git clone http://tohjo.ez.lv/citidev/nlua.git
$ cd nlua
$ git submodule update --init --recursive
$ cd Core/KeraLua/external/lua/
$ cmake .
$ make -j4
$ cp -a lib/liblua52.so $CITIZEN_SRC/CitizenMP.Server/bin/Debug/
$ cd ../.. # into Core/KeraLua
$ ./autogen.sh
$ make # this will error out; not a problem
$ cp -a src/bin/Release/KeraLua.dll $CITIZEN_SRC/CitizenMP.Server/bin/Debug
```
6. Run the CitizenMP server!
```
$ cd $CITIZEN_SRC/CitizenMP.Server/data
$ mono ../bin/Debug/CitizenMP.Server.exe
```
## Configuration
Configuring the current version of the server is done through the citmp-server.yml file, or another .yml file passed as a parameter to the server executable.
\ No newline at end of file
---
title: Resource definition files
---
# Resource definition file (\__resource.lua)
This document lists valid directives provided by the core and other resources for the resource definition file (\__resource.lua).
## Directives (general info)
A directive is basically a Lua function invoked by the 'identifier followed by string or table equals a call' rule - unknown directives are handled by returning a dummy function instead of nil (this means any undefined variable is actually a function - keep this in mind!). In effect, the following are equal:
```lua
client_script 'a.lua' # implicit call
client_script('a.lua') # explicit call
```
## client_scripts
Lists one or multiple client scripts for the resource. Parsed by both client (to load scripts) and server (to offer scripts for download). Aliased as **client_script**.
```lua
client_script 'client.lua'
client_scripts {
'client1.lua',
'client2.lua'
}
```
## dependencies
Lists one or multiple required resources for this resource. Aliased as **dependency**.
```lua
dependency 'chat'
dependencies {
'dot',
'test'
}
```
## description
Sets the meta field 'description' in the resource's metadata.
```lua
description 'My resource'
```
## exports
Lists one or multiple client-side script exports for other resources to call - these are taken from the resource's global environment. Aliased as **export**.
```lua
export 'getStuff'
exports {
'getStuff',
'getOtherStuff'
}
```
## server_scripts
Lists one or multiple server scripts for the resource. Only parsed server-side. Aliased as **server_script**.
```lua
server_script 'server.lua'
server_scripts {
'server1.lua'
'server2.lua'
}
```
## version
Sets the meta field 'version' in the resource's metadata.
```lua
version '1.0'
```
### Calling an export
An export can be called from any resource on the client (tbi on the server) as follows:
```lua
exports.myresource:getStuff(1, 2, 3)
```
---
title: chatMessage
type: event
---
# chatMessage
## Definition
### Client
```lua
AddEventHandler('chatMessage', function(name, color, message) end)
```
### Server
```lua
AddEventHandler('chatMessage', function(from, name, message) end)
```
## Arguments
* **from**: The network ID of the client sending the chat message.
* **name**: The name of the player sending the chat message.
* **color**: A table containing a RGB color the chat message should be displayed as.
* **message**: The actual chat message.
~~This event can be canceled.~~
\ No newline at end of file
---
title: Events
---
# Scripting events
<% for event in @getCollection('html').findAll({type: 'event'}).toJSON(): %>
* [<%= event.title %>](<%= event.url %>)
<% end %>
\ No newline at end of file
---
title: Your first resource
---
# Your first resource - a basic car spawner
Let's start demonstrating the interaction between client and server resources and events by making a simple resource that will spawn a car when a message in the chat equals 'car'.
As stated in the previous page, creating a resource requires you to make a subfolder, and a \__resource.lua file. Therefore, we will make a folder called **mycar** in our resources/ folder, and create a new file called \__resource.lua in the same directory.
```
A:\citizen-data\resources> mkdir mycar
A:\citizen-data\resources> cd mycar
A:\citizen-data\resources\mycar> notepad __resource.lua
```
The content in this file will be simple - we're just creating a single client script and a single server script:
```lua
description 'my cute car spawner'
client_script 'client.lua'
server_script 'server.lua'
```
As chat messages are primarily handled on the server (as shown in the event documentation -- you'll be referring to it often!), we'll start with the server script. It is as follows:
```lua
AddEventHandler('chatMessage', function(from, name, message)
if message == 'car' then
TriggerClientEvent('mycar:createCar', from, 'turismo')
end
end)
```
The server's primary means of code execution is through events like these - the client also has the ability to create *threads*, which execute in the background together with the game.
As shown in the documentation for [chatMessage](events/chatMessage.html), the first argument is the client ID of the player who sent the chat message. The 'mycar:createCar' event is our custom one, which we'll implement below.
Going from there, we're going to be creating the client script. We'll show a basic example of the base framework, explain it, then continue on adding vehicle spawning.
```lua
AddEventHandler('mycar:createCar', function(model)
-- ...
end)
```
Again, this is another event handler as above.
Now, to actually spawn a vehicle, some knowledge of single player GTA scripting is fairly helpful. There are various guides available both for the GTA III series which partially apply here, and somewhat less guides for IV. Basically, to create a local entity, one starts by loading a model. This could be done like this, kind of:
```lua
local hash = GetHashKey(model, _r)
RequestModel(hash)
LoadAllObjectsNow()
```
This shows the way we interact with the game fairly clearly, as well - these functions are the so-called 'native functions' from the game, and are [listed](http://www.gtamodding.com/index.php?title=List_of_native_functions) on various sites. These functions may return various return value types, such as 'results' and have 'pointer arguments'. The **\_r** in this example stands for 'return **r**esult as integer', and a full list follows:
| Variable | Effect |
| -------- | ------------------------------------------------------------------ |
| none | return result, with 0 being converted to a boolean |
| _r | return result as integer, without boolean conversion |
| _b | return result as a boolean, even if a pointer argument is returned |
| _rf | return result as a floating-point value |
| _s | return result as a string |
| _i | return pointer as integer |
| _f | return pointer as floating-point value |
If multiple reference items are specified, the return values will occur from left to right, like the following:
```lua
local x, y, z = GetCharCoordinates(ped, _f, _f, _f)
```
However, there's some issue with this model loading code, which has to be resolved in a better way: as loading a model may take a while, and the player is, well, playing the game, it's usually a good idea to load the model asynchronously. This is typically done in native script by invoking a 'wait' command/function in a loop - and it's no different here...
... except you need a thread for this. Threads in CitizenMP are simply Lua 'coroutines', and therefore if you're used to threads being a 'bad thing', they're typically not over here. Let's show how to actually do this:
```lua
-- hash and such
CreateThread(function()
RequestModel(hash)
while not HasModelLoaded(hash) do
Wait(0)
end
-- do stuff with your model
MarkModelAsNoLongerNeeded(hash)
end)
```
This also introduces another new concept - marking models as 'no longer needed'. If one is not going to perform further script operations on any game resource (whether it be an entity or model), it's recommended to mark them as unneeded - this allows the game to release the memory resources required for this resource (that's a lot of resource :) when it's able to.
Now that we have the model loaded, we can actually continue by creating our car. This usually ends up being done as follows:
```lua
local x, y, z = GetCharCoordinates(ped, _f, _f, _f)
local car = CreateCar(hash, x + 1, y, z, _i, 1)
WarpCharIntoCar(ped, car)
-- this doesn't work in current CitizenMP, sadly - it's kind of needed to allow cars to despawn safely
-- MarkCarAsNoLongerNeeded(car)
```
If we put it all together, as shown below...
```lua
AddEventHandler('mycar:createCar', function(model)
local hash = GetHashKey(model, _r)
CreateThread(function()
RequestModel(hash)
while not HasModelLoaded(hash) do
Wait(0)
end
local x, y, z = GetCharCoordinates(ped, _f, _f, _f)
local car = CreateCar(hash, x + 1, y, z, _i, 1)
WarpCharIntoCar(ped, car)
MarkModelAsNoLongerNeeded(hash)
end)
end)
```
... we have our complete client script!
Let's try it out: add a line to your server .yml file's AutoStartResources section to list 'mycar', start the server, join, and type 'car' in the chat. If everything's okay, you should be put in a Turismo just fine! If not...
## Troubleshooting
... todo ...
\ No newline at end of file
---
title: AddUIHandler
type: function
funcScope: client
---
# AddUIHandler
Adds a handler for an UI RPC command.
```lua
AddUIHandler(string commandName, function cb)
```
## Arguments
* **commandName**: The command to be handled. This will be requested using **http://[resource]/[command]**.
* **cb**: The callback. Arguments to it are 'table data, function completionCB'.
## Example
```lua
chatBuffer = { 5, 6, 7 }
AddUIHandler('getNew', function(data, cb)
cb(chatBuffer)
chatBuffer = {}
end)
```
\ No newline at end of file
---
title: PollUI
type: function
funcScope: client
---
# PollUI
Sends a polling message to the current resource's UI instance.
```lua
PollUI()
```
\ No newline at end of file
---
title: SetUIFocus
type: function
funcScope: client
---
# SetUIFocus
Sets the input focus to the UI layer.
```lua
SetUIFocus(boolean focus)
```
## Arguments
* **focus**: Whether focus is to be given (true) or taken (false) to/from the UI.
\ No newline at end of file
---
title: Functions
---
# Client functions
<% for event in @getCollection('html').findAll({type: 'function', funcScope: 'client'}).toJSON(): %>
* [<%= event.title %>](<%= event.url %>)
<% end %>
\ No newline at end of file
---
title: Client
---
# Client functions
<% for event in @getCollection('html').findAll({type: 'function', funcScope: 'client'}).toJSON(): %>
* [<%= event.title %>](<%= event.url %>)
<% end %>
\ No newline at end of file
---
title: Scripting Reference
---
# CitizenMP:IV script reference
This set of documents details the base scripting features for CitizenMP:IV, and potentially other instances of the CitizenMP framework on other RAGE titles.
## Establishing a baseline
First, we will describe a few terms related to CitizenMP scripting. It is assumed the reader has some [Lua](http://lua.org/) knowledge, or general knowledge of dynamically-typed programming languages.
**Resource**: A package of server scripts, client scripts, user interface files and other components belonging together.
## Creating a resource
The server working directory contains a **resources/** folder, which contains multiple subfolders. Any subfolder marked with square brackets (like **[test]**) will be marked as a 'category' folder, any other subfolder will be parsed as a resource. This means that during server startup, a file called __resource.lua inside the folder will be read and executed.
This file, for instance, will [contain](http://tohjo.ez.lv/citidev/citizenmp-server/blob/master/CitizenMP.Server/data/resources/%5Bsystem%5D/sessionmanager/__resource.lua) something like the following:
```lua
client_scripts {
'client/initial.lua',
'client/leavehandler.lua',
'client/activationhandler.lua',
'client/hostservice.lua',
'client/sessionstarter.lua'
}
server_script 'server/host_lock.lua'
export 'serviceHostStuff'
```
As should be clear from this, it will load those scripts whenever executed on either the client or the server, and will also 'export' a function called **serviceHostStuff** to external resources. For a full description of \__resource.lua, see the [__resource.lua documentation](__resource.html).
As another example, the directory tree for a resource will look somewhat like this:
```
chat
│ chat_client.lua
│ chat_server.lua
│ test.html
│ __resource.lua
└───html
chat.css
chat.html
chat.js
jquery.faketextbox.js
```
This also shows there is no required convention for naming resource files, with one exception: at this time streaming files (which come with its own set of restrictions, as documented on the [streaming file documentation](streaming.html) page) need to be in one specific subfolder of the resource, namely 'stream'.
## Base RAGE scripting concepts
Unlike most other GTA multiplayer modifications, the CitizenMP series runs most game interaction code on the client. This means that most commands (such as creating entities, giving weapons or anything else) are executed on the client.
For an explained example of a basic resource performing simple tasks, continue on to the [explained example resource](example.html).
\ No newline at end of file
---
title: Streaming files
---
# Streaming/CdImage files
CitizenMP:IV has the ability to override/insert files that would normally be placed in 'CD images' (.img files) at runtime. This, however, is bound to a few specific limitations:
1. **No API.** These files are simply loaded from a folder, without any exclusions specifiable.
2. **Only at initialization.** Streaming overrides only get initialized during game initialization, which basically means 'during connecting to the server'. Dynamic resource starting/stopping won't allow overriding these in the current version, and may not do so for a while to come.
## Usage
To use this feature, simply create a folder titled **stream** in a resource folder (one that is started by AutoStartResources, preferably) and place streaming files (.wft, .wtd, .nod, .sco, ...) in there. These will only be downloaded on demand (i.e. when said streaming object is requested, for instance by a call to RequestModel) and will be cached on the client locally for future usage.
The folder's content can be categorized in subfolders for organization, these have no meaning to the game whatsoever.
\ No newline at end of file
---
title: Documentation
menuIcon: book
---
# CitizenMP documentation
<div class="contains-blocks">
<div class="docs-block docs-admin">
<a href="01-admin-guide/">
<strong>Administration Guide</strong>
<span>Instructions and details on setting up a server.</span>
</a>
</div>
<div class="docs-block docs-script">
<a href="02-script-reference/">
<strong>Scripting Reference</strong>
<span>Documentation on CitizenMP-specific scripting details, including how to create a resource and keep it.</span>
</a>
</div>
</div>
There may not be much documentation available now, but despite that, there should be sufficient details for anyone to enjoy.
\ No newline at end of file
---
title: Home
docClass: big-hello
---
<div class="hello">
<div class="breaker">
<img src="http://dotbas.net/i/fiefdom.png" alt="hey" />
<div>
<h2>The multiplayer component you've <em>dreamt</em> of</h2>
<p>CitizenFX<span class="iv">:IV</span> provides the multiplayer component you've been wanting. Even if you don't care about multiplayer at all.</p>
</div>
</div>
<div class="intro">
<p>
CitizenMP<span class="iv">:IV</span> is a multiplayer modification for the 2008 PC port of Grand Theft Auto IV, which differs from other
multiplayer modifications in that it doesn't <em>reimplement</em> networking frameworks, but <em>builds upon</em> the powerful framework
by the Rockstar Studios, as also used in Max Payne 3 and Grand Theft Auto V.
</p>
<p>
This allows for various features such as full support of the artificial intelligence features as seen in the singleplayer and cooperative
gamemodes of IV, near-flawless synchronization of any supported object and is added to by high-level scripting and flexibility features
provided by the CitizenFX framework.
</p>
<p>
The CitizenFX<span class="iv">:IV</span> framework is a multiplayer-first framework supporting the CitizenMP modification, but can also
be used as a base framework for any other modification as desired by developers anywhere - supporting <em>great</em> gameplay experiences.
</p>
</div>
</div>
</div>
</div>
<div class="body">
<div class="container">
<div class="center">
<div class="download">
<a href="http://citizen.re/files/iv-temp.zip"><i class="fa fa-download"></i><strong>Download CitizenMP:IV</strong><span>Automatic updater (requires GTA IV 1.0.7.0/EFLC)</span></a>
</div>
</div>
\ No newline at end of file
// out: ../style.css
.body a
{
color: #06f;
text-decoration: none;
}
.body a:hover
{
color: #09f;
text-decoration: underline;
}
* {
margin: 0px;
padding: 0px;
}
body
{
font-family: 'Segoe UI', sans-serif;
background-color: #fff;
color: #222;
}
img
{
max-width: 100%;
}
#header
{
padding-top: 15px;
background-color: #000;
color: #eee;
}
.container
{
margin-left: auto;
margin-right: auto;
width: 1200px;
position: relative;
}
.logotype
{
-webkit-font-smoothing: antialiased; /* screw Trident/Gecko, they have weird fonts anyway :-) */
font-family: 'logotype';
font-size: 3.0em;