Re: Scripting Documentation / Tutorial Thread

**Zander** Sun Jul 17, 2011 2:53 pm

lemmy101 wrote:In preparation for the modding scripting support, here is some info on it.

There will be a scripts directory within the game folder that contains all scripts in the game in various script text files. Eventually all the PZ quests, conversations and everything will use these scripts.

As well as that, there will be a mods directory which each mod will have their own scripts directory. These will be loaded automatically on the game start up (the mod load order somehow specifiable)

A script is a combination of one or more objects. These can be doors, characters, waypoints or scripts (and ultimately many more). They all look as follows:

Code:
// This is how to declare an object in script. objecttype name { contentsofobject }

Here are a list of different objects and how they are used:

[size=150]Waypoint[/size]

A waypoint is a script representation of a location on the map. We will add a debug mode to allow you to see the x, y, z coordinate of Bob's current position. You can type these coordinates into the waypoint and give it a name to ease in referring to that location in your scripts.

E.g.

Code:
waypoint UpstairsNearBed { 39, 24, 1 }

Here is a waypoint next to the bed in the tutorial start bedroom. You can get a character to walk here, and they will navigate themselves to that position, e.g.

Code:
Raider.Walk(UpstairsNearBed);

[size=150]Character[/size]

This is how you create characters. Example as follows:

Code:
character Raider { GunNut, Bobby, Collins }

This will create a character referred to as 'Raider' in code. At the moment the only three parameters are 'GunNut', which specifies the personality of the NPC (GunNuts look like the raider, have a shotgun/baseball bat, and are aggressive) the other two are obviously his first and last names.

The above character can then be refered to in script as Raider, for e.g.

Code:
Raider.Walk(WaypointName);

Note that creating a character like this only creates the template, and does not put them into the world. to do this you need to call:

Code:
Raider.Actualize(WaypointName);

This line of script will create the character at the specified waypoint, ready to script other commands to.

[size=150]Room[/size]

A room is, quite predictably, a room within a building. To specify a room use them like waypoints, but when referred to in code it will be targeting the entire room that the specified coordinate falls within, not just the tile. E.g.

Code:
room TutorialBedroom { 39, 24, 1 }

This can be used for example in checking if the character is within a specified room, which we will see below.

[size=150]Script[/size]

This is the biggie. Here you can have numerous sequential commands that will be carried out when the script is run. It will go through one by one, moving onto the next once the last has been completed. Each is on a new line and has a semi-colon at the end to specify the end of the line. E.g.

Code:
script RaiderEnter { Raider.Actualize(InsideTutorialDoor); Raider.Walk(UpstairsTutHouse); Raider.Walk(UpstairsNearBed); Raider.Face(NE); Raider.Say("Nick is a silly face."); }

The above code will actualize the defined Bobby Collins raider next to the front door, walk upstairs, into the bedroom, then he will face north east (north is up/right, so NE is facing to the right) and then the raider will speak some supreme truth about nick's silly face.

[size=150]If statements[/size]

You can have if statements that only process the commands inside the braces if the condition is true. e.g.

Code:
script RaiderEnter { Raider.Actualize(InsideTutorialDoor); Raider.Walk(UpstairsTutHouse); Raider.Walk(UpstairsNearBed); Raider.Face(NE); if(Player.Room == TutorialBedroom) {    Raider.Say("Hey Baldspot, I'm going to kill your wife!"); } Raider.Say("3"); Raider.Say("2"); Raider.Say("1"); }

The above script will make Bobby say "Hey Baldspot, I'm going to kill your wife!" only if the player is in the TutorialBedroom defined above. Otherwise if the player is elsewhere, he'll just skip to the countdown.

The script is C like, so conditions are as follows:

== - Equals
!= - Doesn't equal

We'll add more conditions later, but these are the important ones.

[size=150]Overrides[/size]

At the moment the entire tutorial is hard coded into the game code, but in time all our story/quest/conversations will use these scripts.

Since it's never a good idea to change the game data files, since updates will likely undo your work and it'll mean multiple mods will not be compatible, you can use the override command to override any object or script in the base PZ scripts from your own separate mod script, or in any other mod loaded before yours.

For example, let's pretend that the above code:

Code:
script RaiderEnter { Raider.Actualize(InsideTutorialDoor); Raider.Walk(UpstairsTutHouse); Raider.Walk(UpstairsNearBed); Raider.Face(NE); if(Player.Room == TutorialBedroom) {    Raider.Say("Hey Baldspot, I'm going to kill your wife!"); } Raider.Say("3"); Raider.Say("2"); Raider.Say("1"); }

...is the bonafide Project Zomboid game script. You want to mod it. How?

Just create a 'myscript.txt' in your mod scripts directory, and do this:

Code:
override script RaiderEnter { Raider.Actualize(InsideTutorialDoor); Raider.Say("Oh balls, I've been modded. TO DEATH!"); Raider.Die(); }

Since your mod is loaded after the main game, you can override the RaiderEnter script using the 'override' label, and when the game is running it will call your script instead of the base PZ one.

This means that if there's an update, your mod should still continue to work. It also means that multiple mods will usually work together fine, as long as they don't change the same stuff in ways that conflict.

In a similar way, you could rename the raider by adding this to your mod script:

Code:
override character Raider { GunNut, Bill, Smith }

Is he now your brother? Oh my!

[size=150]Items[/size]

You can add items by doing the following:

Code:
item SuperBread { Type=       Food, DisplayName=    Super Bread, Icon=       Bread, ActualWeight=    0.2, HungerChange=    -80, DaysFresh=    3, DaysTotallyRotten= 6, } item Shotgun { Type=       Weapon, Icon=       Shotgun, Ranged=       true, MaxRange=    8.0, MinAngle=    0.88, MaxDamage=    1.8, MinDamage=    1.5, MinimumSwingTime= 0, SwingSound=    shotgun, WeaponSprite=    shotgun, AngleFalloff=    true, SoundVolume=    40, ToHitModifier=    1.5, SoundRadius=    50, OtherCharacterVolumeBoost=1.5, ImpactSound=    null, SwingTime=    1.1, KnockBackOnNoDeath= false, SplatBloodOnNoDeath= true, SwingAmountBeforeImpact = 0.0, AmmoType=    ShotgunShells, DoorDamage=    20, ActualWeight=    25 }

There are countless other parameters. We'll detail these later.

As well as creating new items, you can also use override to change one aspect of an existing item, e.g...

Code:
override item Shotgun { MaxRange=    16.0, DisplayName= Super Shotgun, }

The above doubles the range of the shotgun and renames it to Super Shotgun.

[size=150]Crafting Recipes[/size]

Code:
recipe Molotov { WineEmpty, PetrolCan, DishCloth, null, Molotov, 3.0 } recipe Molotov2 { WineEmpty, PetrolCan, RippedSheets, null, Molotov, 3.0, } recipe SpikedBat { BaseballBat, Nails, keep Hammer, null, BaseballBatNails, 5.0, }

First four parameters are the four source items, use null to ensure one or more spaces are blank, 'keep' before the item name means the item will not be consumed when used in crafting. Next parameter is the resulting item. Last parameter is the base number of seconds to make one item.

More to come!