[VC|SCM] samenvatting in het engels.

[Ken-D]

De topic titel klinkt nogal stom maar ik zal ik het proberen in het kort uit te leggen.Er zijn wel tuts hoe je wapens zo plaats en wagens daar plaatst maar ik zou wat meer info over de variable,integers.Defines etca willen weten.Waar dienen ze voor etca.Als iemand me hiermee kan helpen.

Alvast bedankt.

Postaldude

[PatrickW]

Zo'n tekst bestond tot voor kort helaas nog niet,

Ik ben wel bezig het te schrijven, maar het is nog niet compleet

( en helaas alleen nog in het engels beschikbaar).

Hieronder vindt je de eerste opzet van deze tekst, en zoals je zien ontbreekt de inhoud van het laatste deel nog, daar wordt nog aan gewerkt.

Als het klaar is, wordt het misschien nog wel in het nederlands vertaalt ( eclipse ?? )

----------------------------------

====================================

Essentials of scm modding for GTA-VC

By patrickW

====================================

Content

-------

1. Introduction

2. Layout and syntax

4. Pitfalls

5. Entry-level modifications

6. Advanced Coding Patterns

1. Introduction

---------------

This is not a scm modding tutorial, but a document that describes the essential concepts of scm modding. It is meant to be an addition to the documentation supplied with your tool. A large piece of the information here will also be in the tool documentation, but it never hurts to read important information again in a different form.

1.1 What does the main.scm file do?

The main.scm file contains the instructions that initiate and control most of the activity that happens inside GTA-VC. I also determines locations and properties of dynamic objects in the game like pick-ups and parked cars.

By editing this file, you have almost infite amount of possibilities to change the game from simple things like changing a parked car to complete new missions.

1.2 What tools are available?

Since main.scm is not a simple textfile, you can't edit it with ordinary tools like notepad. Dedicated tools are available that convert the binary main.scm file into a textfile(disassembling), allow you to edit this textfile and are able to convert it back into a new binary file (assembling or compiling).

The available toolsets are (in order of popularity):

- Vice Mission Builder v1.3

- Vice Mission Builder v0.22

- GTAMA

Note that the popularity does not necessary match the quality of a tool. Wars have been started about the question which tool is the best, so I won't be commenting on that.

Sadly, all the tools use a different syntax for the text-version of the main.scm file, which might be confusing if you stumble upon code made for another tool than the one you're used to.

In this document I'll be using the syntax of "Vice Mission Builder V1.3", because that is the most popular one at the moment, and happens to be the one I'm most familiar with.

Most information presented here can easily be projected onto the other syntaxes.

1.3 How do I learn main.scm modding?

Learning main.scm modding is not a simple task, and it takes some effort and dedication to master it. Although simple modifications may be made by just working through one of the available tutorials on the net, if you want to make some real changes you'll have to dedicate a large amount of your time to study the original Rockstar code, collect information available in the community and do a lot of experimenting and testing.

Here's a list of the most essential resources needed to master main.scm coding:

- Documentation of your toolset

- Original Rockstar code

- gtaforums.com

- opcode database (using GTAMA-syntax)

- and offcourse this document.

<Add various URLS>

2.Layout and Syntax

-------------------

This chapter explains the structure of the main.scm file. First the global structure is described with an overview of the four sections:

- Memory reservation

- Object definition

- Mission definition

- Code

The remainder of this chapter is dedicated to describe the syntax of the CODE-section

2.1 global structure

The main.scm file consists of 4 sections.

<picture of the four sections>

The first section contains the memory reservations for global variables, and is represented in the textfile with "DEFINE MEMORY xxxxx". You should leave the number always at its original value, unless the compiler instructs you to change it, during the compilation process.

The second section is the object-definition section, which contain a list of all the dynamic objects that are manipulated by the main.scm file. Objects are numbered in the comment behind it, and these numbers are used in the remainder of the main.scm file to reference these objects. For this reason, you should never-ever remove an object from this list, and if needed add new objects to the end of the list. Otherwise all the references in the main.scm file will pointing to the wrong objects.

The third section contain the mission definitions, these are references to the start-addresses of the various missions. Their usage will be described in 2.6.7

The fourth and by far the largest section "Code" contains the instructions (opcodes) that initiate and control most of the activity in the game. This section itself consists of two parts, the first part "MAIN" contains all general code. The second part "MISSIONS" contain the code that is only executed after the player has activated one of the games missions.

The MISSIONS part can be further divided into the code for each of the MISSIONS. These two parts will be handled differently by the game-engine, but the main reason to make this distinction is in the differences in label referencing, described in 2.6.1 .

2.2 datatypes and variables

Before I will describe the syntax used for these opcodes, I first have to introduce some important concepts.

2.2.1 datatypes

The main.scm works with three basic types of data:

- floating point data ( 0.42 )

e.g. used for coordinates, angles

- integer data ( 42 )

e.g. used for counters, index, handles, refrences, labels

- String data ("RACE_TM" )

e.g. used for GXT-keys, thread_names

In general, every opcode does require that each of its parameters is of the correct datatype. Failure to do so will result in "unexpected behaviour".

The types of parameters that opcodes require can be seen in the existing code, and is documented in the opcode-database.

2.2.2 variables

Variables are locations where a value can be stored for later use. A variable can contain a floating-point or an integer value. There are two types of variables used in main.scm:

- global variables (e.g. $my_variable)

- local variables (e.g. 2@)

The difference between global and local (apart from the notation) is that global variables are always accessable and local variables are only accessable from within the same thread/mission that created them.

Global variables are referenced by a name starting with a '$'. Each variable needs a unique name, and that name consist of alphanumerical characters. The name you choose for new variables does not matter, as long as it's unique. When the main.scm is disassembled, some global variables will get meaningfull names, but most of them are just named with a hexadecimal sequence number, that has no other meaning than to just uniquely identify that variable

Local variables are referenced by a number followed by a '@'. Local variables 0 to 15 can be used to store values, while 16 and 17 are counters that are incremented each msec. These last two can be written to give them an initial value and can be read to obtain the current value.

2.3 comments

Comments can be added to the textfile to clarify a piece of code, all comments should be preceeded by ';'. Everything between ';' and the end of the line is ignored by the compiler.

2.4 opcode syntax

The syntax is line based, and every line that contains an instruction has the following layout:

opcode: parameter1 parameter2 ....

In front, between and after the parameters there will often be command-text, that describe what the opcode does. But these are only there to improve human readibility, and are ignored when the file is compiled into binary form again.

The opcode consists of 4 hexadecimal character (0-9 and a-f), and uniquely identifies the operation that has to be performed. Each parameter can be one of the following:

- Literal integer value ( e.g. 42 )

- Literal float value ( e.g. 42.0 )

- Reference to a global variable ( e.g. $my_var )

- Reference to a local variable ( e.g. 2@ )

- Reference to an item in the default.dat (e.g. #ARMY, #INFERNUS )

- Reference to a label (e.g. LLlabel_apple or Llabel_pear) ( see 2.6.1)

- Literal string value (e.g. "PACKAGE")

Any text found behind the opcode that doesn't match any of the above parameter types, is considered to be command text, and will be ignored by the compiler.

2.5 Available opcodes

A lot of the opcodes that can be used in the main.scm have been identified by the brave pioneers of scm modding. There remain however a significant amount of opcodes that are used in the main.scm of which the meaning is yet unknown.

The most up-to-date overview of available/indentified opcodes can be found at the opcode-database (see ch.1 for URL). It also contains info on the parameters for the various opcodes. Also check the "mission coding discussion" forum at gtaforums.com for the latest opcode discoveries.

2.6 flowcontrol mechanisms

Normally opcodes are executed in sequence as they appear in the scm, but there are several mechamisms available that change this.

2.6.1 Labels

:label_somewhere

This puts a name on a location in the scm file, so that one of the flow-control opcodes described here can reference it. Labels are referenced by the labelname, preceded by one or two "L". The distinction between these has to do with the distinction between the two parts of the code section; "MAIN" en "MISSIONS".

Labels in the MAIN part are referenced with LL, and are accessable from both the MAIN part as well as the MISSIONS part.

Labels in the MISSIONS part are referenced with L, and are only accessable from within the code of the same mission.

2.6.2 jumps

0002: Jump LLlabel_elsewhere

This makes the next opcode to be executed the one below the label that is given.

Jumps are allowed within the MAIN part, and within a MISSION, but not between the two parts.

2.6.3 conditional jumps

nnnn: if X

<any condition>

::::::::::::::

<other condition>

nnnn: jump_if_false LLlabel_elsewhere

The if and jump_if_false opcodes, should always come in pairs, surrounding one or more conditions (upto 8 conditions are supported).

A condition is an opcode that yield a TRUE/FALSE result. A whole range of condition opcodes are available from simple comparision of two variables to the check wether or not the player is in a certain area of the game world. Wether or not a opcode is a condition can be seen, by looking how it is used in the original R* code.

The parameter of the if opcode (X) serves two goals, it indicates the number of conditions, and when there are multiple conditions; how the results of the individual conditions should be combined into one.

There are two possibilities for combining multiple conditions:

- AND: result is only TRUE if all individual conditions are TRUE

- OR: result is TRUE if any of the individual conditions are TRUE

The if parameter (X) can be determined as follows:

X = 0 if there is only one condition

X = n-1 if there are n conditions, to be combined with AND

X = n+19 if there are n conditions, to be combined with OR

If the set of conditions gives a FALSE result, the next opcode to be executed is the one following the label given by jump_if_false.

If the set of conditions gives a TRUE result, the next opcode to be executed is the one below the jump_if_false opcode.

Conditional jumps are allowed within the MAIN part, and within a MISSION, but not between the two parts.

2.6.4 subroutines

nnnn: gosub LLlabel_routine

....

....

...

:LLlabel_routine

....

....

....

nnnn: return

The gosub act just as a jump, in that it will continue with the opcode following the given label. As a bonus, however, it remembers the position of the opcode below the "gosub". When the code, after jumping the label,reaches a "return" opcode, it will jump back to the remembered location. This will enable you to jump the a piece of code from different locations,and continue where you were when that piece of code is finished.

Gosubs to the MAIN part are allowed from both the MAIN part itself as the MISSIONS part. Gosubs to the MISSIONS part are only allowed from inside the same mission.

2.6.5 Threads

The main.scm file is processed by multiple threads.This might be one of the most difficult concepts to grasp for someone not familiar with multi-threading programming. So don't dispear if you don't get it right away, you're not alone.

Uptill now, we described the code as being executed opcode after opcode, sometimes jumping to a different location and continueing. Imagine this process being executed by a little guy inside your computer. He spends all day reading an opcode, executing it, determining the next opcode to execute, read it and execute it, day-in day-out. Lets call this little guy "thread".

Now image that this guys has a brother, who does exactly the same thing. Offcourse they're not looking at the same opcodes at the same time, his brother is working on another part of the code. Both are working indepently of each other, reading opcodes, executing them, determining next opcode, ... Can you image that ??

Now image that there's a whole family of those little guys, all doing the same thing on different parts of the code.

~~~~~Welcome to the world of multi-threading. ~~~~

Now how do we manage these threads ?

At the beginning there's only one thread that starts to execute at the beginning of the main.scm file, called the main-thread. Through a serie of jump's it will skip the first three sections and arive at the beginning of the code-section. There it will perform some initialisation, until it encounters a series of "create_thread" opcodes.

nnnn: create_thread LLlabel_thread

That opcode creates a new "little guy" (thread) that starts executing opcodes below the given label. In this way, the main-thread creates a whole army of threads, each working on a specific part of the code, to perform a dedicated task. Some of the threads live indefinitly, just looping around the same code. Other threads only have to perform a single task once and kill themself upon encountering an "end_thread" opcode.

nnnn: end_thread

A thread can also kill another thread, by supplying name of its victim as a parameter to the end_thread opcode. Threads are given a name, when they execute a "name_thread" opcode, which is normally one of the first opcodes they encounter.

nnnn: end_thread "MY_BRO"

Create_thread may be executed from both the MAIN part as well as the MISSIONS part. The code that the thread will execute however, must be located in the MAIN part.

2.6.6 Wait-opcode

nnnn: wait 250 ms

This opcode seems really straight forward, it suspends the current thread for the given amount of ms. There is however a deeper meaning of the wait opcode. Do you remember all those little guys described earlier, all working on the code at the same time? I lied a little, these guys aren't actually working on the code all at the same time, but they take turns. Imagine all the little guys sleeping, and the system wakes each of them in turn, and that one works until he encounters a wait-opcode. At that time, he tells the system not to wake him for the given amount of time and the little guy goes to sleep. The system will than do some work of its own and wake up the next guy.

"Why should I care?", you might ask.

Well, when writing code, you have to make sure that each thread runs into a "wait" once in a while, otherwise that thread will never goto sleep to allow the system and the other threads to do some work. As a rule, every loop in your code should at least contain one wait-opcode. Failure to do so, will result in a lock-up of the game.

2.6.7 Missions

If you read carefully until here, you might ask yourself, "How we can execute opcodes that are located in the MISSIONS section?", as we can't jump/gosub there from the MAIN part, and we may not start threads there. The answer to this is the start_mission opcode:

nnnn: start_mission X

This will start a mission thread at the label given in the mission definition section for mission X.

Mission threads are a lot like normal threads, but have some additional functionality, but this is beyond the scope of this document.

Adding custom missions to the main.scm file is the most difficult type of scm modification, so be prepared to spend a lot of effort. If you want to add your own missions, be sure to closely follow the template given in 5.6. It already contains all the opcodes to correctly end a mission-thread.

3. Pittfalls

---------

<Copy from the earlier published scm checklist> and Edit

4. Entry-level modifications

-------------------------

4.1 Adding, moving or modifying car_generators

4.2 Adding, moving or modifying pickups ( health, bribe, adranaline, armour, weapons )

4.3 Adding or moving hidden packages

5. Advanced Coding Patterns

---------------

5.1 Actors

5.1.1 Creating normal

5.1.2 Creating special actor

5.1.3 Actor with weapons

5.1.4 Movement

5.1.5 Behaviourals

5.2 Vehicles

5.2.1 Creating

5.2.2 Adding actors

5.2.3 Movement

5.3 Objects

5.3.1 adding new one to the OBJECT TABLE

5.3.2 Creating

5.3.3 Movement

5.4 Audio: playing wav, single SFX and looping SFX

5.5 Using Arrays

5.6 Creating Custom Missions

[Eclipse]

Als het klaar is, wordt het misschien nog wel in het nederlands vertaalt ( eclipse ??   )

tjaaa..het is een hele lap teks te

Ik die het op 1 voorwaarde.

Als ik het ook op mijn site mag zetten (met natuurlijk jouw naam erbij he)

[Ken-D]

Een hele lap tekst Patrick maar mooi gedaan.

ik ben scm modden nou beter te begrijpen.

Postaldude

[PatrickW]

eclipse: Tuurlijk mag je het plaatsen, alles wat ik maak/schrijf is public domain, dus iedereen mag er mee doen wat ze willen, zolang ze mijn naam vermelden.

[Eclipse]

oke ik zal kijken wat ik er mee kan doen