Skip to content

Commit

Permalink
Merge pull request #92 from muczc1wek/dev-1
Browse files Browse the repository at this point in the history 
New daedalus classes and zSpy article
  • Loading branch information
@auronen
auronen authored Jul 7, 2023
2 parents 69015d4 + 81e89c5 commit 1100c33
Show file tree
Hide file tree
Showing 8 changed files with 476 additions and 3 deletions.
2 changes: 1 addition & 1 deletion docs/zengin/general_info/object_persistence.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,7 +45,7 @@ This property might not be present in older archives.
This is the most important part of the header as it specifies in which format should the data be stored. There are 4 different modes:

- **ASCII** - The simplest one. It stores data in human-readable ASCII notation (not unlike JSON for example). This is usually used when saving data during development and/or testing, while the final version of said data will most likely be stored as BIN_SAFE.
- **ASCII_PROPS** - Same as ASCII except with more additional data that the developer can specify for visual clarity. In practice, it is not used anywhere and mostly serves only to prettify debug info (try typing `ZWORLD VOBPROPS` in the console and look in zSpy ;) ).
- **ASCII_PROPS** - Same as ASCII except with more additional data that the developer can specify for visual clarity. In practice, it is not used anywhere and mostly serves only to prettify debug info (try typing `ZWORLD VOBPROPS` in the console and look in [zSpy](../tools/zSpy.md) ;) ).
- **BINARY** - Binary representation of the class instance, which mostly copies the data 1:1 into/from the stream. In practice, this format is only used to store savefiles (.SAV).
- **BIN_SAFE** - BinSafe, short for Binary Safe, is an extended version of Binary which stores type information along with the data itself. This is meant to make error checking for invalid data easier. There are other changes which are explained below. Most, if not all world files (.ZEN), are stored in this format.

Expand Down
179 changes: 179 additions & 0 deletions docs/zengin/scripts/classes/c_menu.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
---
title: C_MENU
---

# C_MENU Daedalus class

!!! example "Acknowledgment"
Heavily inspired by the amazing documentation site [Gothic library](http://www.gothic-library.ru)

Class `C_Menu` is responsible for the behavior and properties of the game menus (options, save etc.).
## Class definition
Class definition as it is defined in [`Scripts/System/_intern/Menu.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/_intern/Menu.d) script file.

??? "C_Menu Daedalus class"
```dae
class C_Menu
{
var string backPic; // Menu background image
var string backWorld; // Background ZEN-world of the game menu (Not used)
var int posx; // The top left point of the menu on the screen horizontally (X-axis)
var int posy; // The top left point of the menu on the screen vertically (Y-axis)
var int dimx; // Menu width in virtual coordinates
var int dimy; // Menu height in virtual coordinates
var int alpha; // Menu transparency
var string musicTheme; // Music track of the menu
var int eventTimerMSec; // trigger time for the event EVENT_TIMER
var string items[150]; // Menu items
var int flags; // Menu flags
var int defaultOutGame; // Menu item highlighted by default when the game is not running
var int defaultInGame; // Menu item highlighted by default when the game is running
};
```

## Class members

| Variable | Type | Description |
|-----------------------------------|--------|-------------------------------------------------------------------------------------|
| [backPic](#backpic) | string | Menu background image |
| [backWorld](#backworld) | string | Background ZEN-world of the game menu (Not used) |
| [posx](#posx) | int | The top left point of the menu on the screen horizontally (X-axis) |
| [posy](#posy) | int | The top left point of the menu on the screen vertically (Y-axis) |
| [dimx](#dimx) | int | Menu width in virtual coordinates |
| [dimy](#dimy) | int | Menu height in virtual coordinates |
| [alpha](#alpha) | int | Menu transparency |
| [musicTheme](#musictheme) | string | Music track of the menu |
| [eventTimerMSec](#eventtimermsec) | int | The timer that triggered the event in seconds |
| [items](#items) | string | Menu items |
| [flags](#flags) | int | Menu flags |
| [defaultOutGame](#defaultoutgame) | int | Menu item highlighted by default when the game is not running |
| [defaultInGame](#defaultingame) | int | Menu item highlighted by default when the game is running |


## Class member overview
Description of the class member variables.

### backPic
`backPic` is just a name of background image of the menu in `.tga` format.

### backWorld
!!! Warning "Deprecated setting"
The background world of the game menu in `.ZEN` format.

### posx
The horizontal position of the top left point of the menu on the screen, in virtual coordinates.

### posy
The vertical position of the top left point of the menu on the screen, in virtual coordinates.

### dimx
Menu width in virtual coordinates.

### dimy
Menu height in virtual coordinates.

### alpha
Menu transparency. Accepts values ​​from 0 to 255. Without the `backPic` property specified, the value of this parameter is ignored.

!!! Note
Texture transparency can only be adjusted if the texture has an alpha channel.

### musicTheme
Music theme of the menu.
```dae
instance MENU_MAIN(C_MENU_DEF)
{
...
musictheme = "SYS_Menu";
...
};
```
All instances of musical themes are stored in a file [`Scripts/System/Music/MusicInst.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/Music/MusicInst.d)

### eventTimerMSec
Defines the trigger time for the event `EVENT_TIMER` in seconds.

The list of constants for all menu events is described in the file [`Scripts/System/_intern/Menu.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/_intern/Menu.d#L51)

```dae
const int EVENT_UNDEF = 0; // Undefined
const int EVENT_EXECUTE = 1; // Process start event
const int EVENT_CHANGED = 2; // Menu parameter change event
const int EVENT_LEAVE = 3; // Menu item focus loss event
const int EVENT_TIMER = 4; // Timer fire event
const int EVENT_CLOSE = 5; // Menu close event
const int EVENT_INIT = 6; // Initialization event
const int EVENT_SEL_PREV = 7; // Select event of the previous menu item
const int EVENT_SEL_NEXT = 8; // Select event of the next menu item
```

### items
An array of items belonging to this menu. It is possible to use up to 150 items in one menu. The same elements can be used for different menus. The element instance is specified as the value.

```dae
// Menu
instance MENU_MAIN(C_MENU_DEF)
{
...
items[0] = "MENUITEM_MAIN_HEADLINE";
items[1] = "MENUITEM_MAIN_HEADLINE2";
items[2] = "MENUITEM_MAIN_NEWGAME";
...
};

// Menu elements: labels, checkboxes, sliders, etc.

instance MENUITEM_MAIN_HEADLINE(C_MENU_ITEM_DEF)
{
...
};

instance MENUITEM_MAIN_HEADLINE2(C_MENU_ITEM_DEF)
{
...
};

instance MENUITEM_MAIN_NEWGAME(C_MENU_ITEM_DEF)
{
...
};
```

### flags
Menu flags.

The list of flag constants can be found in the file [`Scripts/System/_intern/Menu.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/_intern/Menu.d#L43)


```dae
const int MENU_OVERTOP = 1; // Show menu over previous menu or in game
const int MENU_EXCLUSIVE = 2; // Close all previous menus. Only the active menu is displayed
const int MENU_NOANI = 4; // No animation
const int MENU_DONTSCALE_DIM = 8; // Don't Scale Menu Sizes
const int MENU_DONTSCALE_POS = 16; // Empty flag
const int MENU_ALIGN_CENTER = 32; // Center Align Menu
const int MENU_SHOW_INFO = 64; // Display information at the bottom of the description menu from menu items text[1]
```

- **MENU_OVERTOP** - Flag to display the menu over the previous menu. It is not advisable to use with a transparent menu.
- **MENU_EXCLUSIVE** - Hide all menus except the active one. When closed, the previous menu is restored.
- **MENU_NOANI** - Animation of minimizing and maximizing windows. The game is mainly used for dialogue windows. You can't enable or disable the animation of dialog windows through scripts. This is done using the `animatedWindows` setting in the Gothic.ini file.
- **MENU_DONTSCALE_DIM** - Scale the menu to fit 640x480 resolution.
- **MENU_DONTSCALE_POS** - Empty flag. Not used.
- **MENU_ALIGN_CENTER** - Align the menu to the center of the screen.
- **MENU_SHOW_INFO** - Display information at the bottom of menu description from menu item `text[1]`.

### defaultOutGame
The menu item that is highlighted by default when the game is not running.

A value of -1 enables automatic selection of the first selectable element.

Items with the `~IT_SELECTABLE` flag are not selected.

### defaultInGame
Menu item highlighted by default when the game is running.

A value of -1 enables automatic selection of the first selectable element.

Items with the `~IT_SELECTABLE` flag are not selected.

59 changes: 59 additions & 0 deletions docs/zengin/scripts/classes/c_musicsys_cfg.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
---
title: C_MUSICSYS_CFG
---

# C_MUSICSYS_CFG Daedalus class

!!! example "Acknowledgment"
Heavily inspired by the amazing documentation site [Gothic library](http://www.gothic-library.ru)


Class `C_MusicSys_CFG` defines the global settings for the game's music.

An instance of this class is declared only once.
## Class definition
Class definition as it is defined in [`Scripts/System/_intern/Music.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/_intern/Music.d#L40) script file.

??? "C_MusicSys_CFG Daedalus class"
```dae
class C_MusicSys_CFG
{
var float volume; // Music volume
var int bitResolution; // Sound quality
var int globalReverbEnabled; // Enable global reverb
var int sampleRate; // Frequency
var int numChannels; // Sound channels
var int reverbBufferSize; // Reverb buffer size
};
```
## Class members

| Variable | Type | Description |
|---------------------------------------------|--------|--------------------------------------------------------------|
| [volume](#volume) | float | Overall game music volume |
| [bitResolution](#bitresolution) | int | Sound quality |
| [globalReverbEnabled](#globalreverbenabled) | int | Enable global reverb |
| [sampleRate](#samplerate) | int | Frequency |
| [numChannels](#numchannels) | int | Number of sound chanells |
| [reverbBufferSize](#reverbbuffersize) | int | The size of reverb buffer |

## Class member overview
Description of the class member variables.

### volume
The overall volume of the background music (soundtrack). From 0.0 to 1.0.

### bitResolution
Sound quality. 8 or 16 bit.

### globalReverbEnabled
Enable global reverb.

### sampleRate
Frequency. From 11050 to 44100.

### numChannels
Number of sound channels. From 16 to 32.

### reverbBufferSize
The size of the reverb buffer.
114 changes: 114 additions & 0 deletions docs/zengin/scripts/classes/c_musictheme.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
---
title: C_MUSICTHEME
---

# C_MUSICTHEME Daedalus class

!!! example "Acknowledgment"
Heavily inspired by the amazing documentation site [Gothic library](http://www.gothic-library.ru)

Class `C_MusicTheme` describes musical themes.
## Class definition
Class definition as it is defined in [`Scripts/System/_intern/Music.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/_intern/Music.d#L52) script file.

??? "C_MusicTheme Daedalus class"
```dae
class C_MusicTheme
{
var string file; // Sound file in DirectMusic `.sgt` format
var float vol; // Sound volume
var int loop; // Enable cycle
var float reverbMix; // Reverb mixing
var float reverbTime; // Reverb time
var int transType; // Type of transition to the next theme
var int transSubType; // Subtype of transition to the next theme song
};
```
## Class members

| Variable | Type | Description |
|-----------------------------------|--------|-------------------------------------------------------------------------------------|
| [file](#file) | string | Sound file in DirectMusic `.sgt` format |
| [vol](#vol) | float | Sound volume |
| [loop](#loop) | int | Enable/disable cycle |
| [reverbMix](#reverbmix) | float | Reverb mixing |
| [reverbTime](#reverbtime) | float | Reverb time |
| [transType](#transtype) | int | The type of transition to the next theme song |
| [transSubType](#transsubtype) | int | The subtype of transition to the next theme song |

## Class member overview
Description of the class member variables.

### file
DirectMusic sound in *.sgt format or MIDI file.

### vol
The volume of the theme song. From 0.0 to 1.0.

### loop
Enable/disable theme music looping. Disabled = 0. Enabled = 1.

### reverbMix
Reverb mixing. Measured in decibels.

### reverbTime
Reverberation time in milliseconds.

### transType
The type of transition to the next theme song.

The list of constants for all transitions types is described in the file [`Scripts/System/_intern/Music.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/_intern/Music.d#L24)

```dae
const int TRANSITION_TYPE_NONE = 1; // No transition
const int TRANSITION_TYPE_GROOVE = 2; // Ripple
const int TRANSITION_TYPE_FILL = 3; // Padding
const int TRANSITION_TYPE_BREAK = 4; // Break
const int TRANSITION_TYPE_INTRO = 5; // Introductory
const int TRANSITION_TYPE_END = 6; // End topic
const int TRANSITION_TYPE_ENDANDINTRO = 7; // End and start new
```

### transSubType
The subtype of transition to the next theme song.

The list of constants for all transitions subtypes is described in the file [`Scripts/System/_intern/Music.d`](https://github.com/VaanaCZ/gothic-2-addon-scripts/blob/Unified-EN/_work/Data/Scripts/System/_intern/Music.d#L33)

```dae
const INT TRANSITION_SUB_TYPE_IMMEDIATE = 1; // Instant transition
const INT TRANSITION_SUB_TYPE_BEAT = 2; // Rhythmic transition
const INT TRANSITION_SUB_TYPE_MEASURE = 3; // Gradual transition
```

## Name features
The musical themes of the game are played depending on the game situation. By default, the theme with the ending is played `_STD` (standard). In case of a threat, the theme will be played with the ending `_THR` (threat). Theme plays during combat `_FGT` (fight).

```dae
instance WOO_DAY_STD(C_MUSICTHEME_STANDARD)
{
file = "woo_daystd.sgt";
};

instance WOO_DAY_THR(C_MUSICTHEME_THREAT)
{
file = "woo_daythr.sgt";
};

instance WOO_DAY_FGT(C_MUSICTHEME_FIGHT)
{
file = "woo_dayfgt.sgt";
};
```
In addition, with the suffix `_DAY_` and `_NGT_` determined by day or night, the theme is played.
```dae
instance OWD_DAY_FGT(C_MUSICTHEME_FIGHT)
{
file = "owp_dayfgt.sgt";
};

instance OWD_NGT_STD(C_MUSICTHEME_STANDARD)
{
file = "owd_daystd.sgt";
};
```
Themes from prototypes are used by default `C_MUSICTHEME_STANDARD`, `C_MUSICTHEME_THREAT` and `C_MUSICTHEME_FIGHT`.
2 changes: 1 addition & 1 deletion docs/zengin/scripts/extenders/lego/applications/console_commands.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ func void CC_Register(var func f, var string cmdPrefix, var string description)
- `#!dae var string cmdPrefix`
This is a command, which can be entered in the console.
- `#!dae var string description`
This text appears next to the command (in zSpy) when you use the `help` command in the console.
This text appears next to the command (in [zSpy](../../../../tools/zSpy.md)) when you use the `help` command in the console.

### `CC_Remove`
Removes a function from the console commands.
Expand Down
2 changes: 1 addition & 1 deletion docs/zengin/scripts/extenders/lego/applications/console_commands.pl.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ func void CC_Register(var func f, var string cmdPrefix, var string description)
- `#!dae var string cmdPrefix`
Jest to polecenie, które można wprowadzić w konsoli.
- `#!dae var string description`
Ten tekst pojawia się obok polecenia (w zSpy), gdy używasz polecenia `help` w konsoli.
Ten tekst pojawia się obok polecenia (w [zSpy](../../../../tools/zSpy.md)), gdy używasz polecenia `help` w konsoli.

### `CC_Remove`
Usuwa funkcje z konsoli komend.
Expand Down
Loading

0 comments on commit 1100c33

Please sign in to comment.