Opening the pk3 included with ECWolf is good when you need to reference the name of a "vanilla" sprite or learn how a particular Decorate actor works, but you should never make changes to the file.

The ecwolf.pk3 file contains the information ECWolf needs to translate and run elements of Wolfenstein 3D, Spear of Destiny, and the other games it is compatible with.

If you make changes to ecwolf.pk3, it can break this compatibility and cause things to be unplayable.

Instead, ECWolf employs soft-modding philosophies, where your mod will be a separate pk3 file with just the modifications you are including. ECWolf will combine it with ecwolf.pk3 and the original game files to be able to play your mod as a complete game.

When adding any game resources to your project, whether replacement sprites or new maps, they will need to be organized into specially named folders so that ECWolf can find them and assign them to their appropriate "namespace":

• Maps go in the /maps directory.
• Sprites go in the /sprites directory.
• Walls, doors, and other texture sprites go in the /textures directory.
• Sounds and music each go in the /sounds and /music directories, respectively.
• Optionally, textures that are specifically for floors and ceilings can go in the /flats directory, to keep things organized.

Depending on the depth of your project, you'll want to have some or all of these folders.

You can create additional subfolders within these folders if you want to organize your files further (such as grouping sprites).

When handling sprites, ECWolf expects a particular structure in how they are named. This is covered in detail in one of the official ECWolf guides, but to summarize, a sprite name is generally six characters long, and can be broken into 3 parts:

1. The first four letters, which is the sprite's name. Groups of sprites, like the sprites for the pistol, will share the same name.
2. The next character indicates the sprite's "frame". The default is A but if a sprite is animated, like a weapon firing, each sprite will move sequentially through the alphabet (The second sprite in the animation will use B, third will be C, etc).
    
    
3. The last character is the rotation number, from 1-8. If the sprite has no rotation as is the case with static sprites and bosses, the number would be 0.
    
    
4. Optionally, a second set of frame and rotation values can be added to the end of a sprite's name to make that frame/rotation a mirror of the sprite.
   As an example, instead of having two separate sprites for the guard standing straight left and right (GARDA3 and GARDA7) you could remove the GARDA7 sprite, and change the GARDA3 sprite's name to GARDA3A7. ECWolf will use the sprite as GARDA3, and flip it horizontally when it needs to be GARDA7.

If you want to create new objects, weapons, enemies, or other features for your ECWolf project, you will want to make use of Decorate!

ECWolf uses a scripting language called Decorate to create and manage features and elements of the game. Weapons, enemies, objects, are all "actors" created in Decorate with different properties, flags, and animation states.

When adding anything along these lines yourself, you will be looking to make your own custom Decorate scripts. For custom scripting, ECWolf looks specifically for a decorate.txt file in the main directory of your project's pk3.

Splitting Decorate scripts into multiple files

If you start adding a lot of scripted things to your project like new objects, enemies, or weapons, you can find this file can get quite bloated. Decorate accounts for this, allowing for you to split scripting into multiple files, as long as they are referenced in the decorate.txt file.

For example, if you put all scripting for custom weapons in a newweapons.txt file, and put that file within a folder called /actors, you would need to put the following #include at the top of your decorate.txt:

#include "actors/newweapons.txt"

Larger mod projects benefit from organization on this level, as it allows you to find things easier and tweak them.

You can learn more about Decorate by reading Blzut3's guide on Creating Mods For ECWolf, and learn more about Decorate on the ECWolf Wiki.

The MAPINFO file is capable of holding a lot more than the basics covered here, including changes to difficulty select, automap and intermission screens. You can learn about all the different elements of MAPINFO on the ECWolf Wiki.

The MapInfo file can be one of the most important in an ECWolf project, as it will contain core information about your game. This file will tell ECWolf how to group and order your episodes and maps, as well as various other core settings.

Let's look at the example version provided by Dunkelschwamm in his guide:

clearepisodes

episode "EXAMPLE"
{
    lookup = "WL_EPISODE1"
    picname = "M_EPIS1"
    key = "E"
}

cluster 1
{
    exittext = "ENDART1"
    exittextislump
}

map "EXAMPLE"
{
    next = "EXAMPLE"
    secretnext = "EXAMPLE"
    floornumber = 1
    par = 90
    music = "GETTHEM"
    cluster = 1
}

This is effectively a blank slate - clearepisodes removes the existing episodes, then a new episode is created, linking to the map "EXAMPLE" as the starting map in the episode.

A cluster is also defined - this allows a mod project to wrap sets of levels with intermission screens at the start or end, allowing for chances to portray additional game information or story elements through text as the game progresses.

The "EXAMPLE" map is then given variables, such as what map to follow with, and if it is part of a cluster.

You can learn the process of adding maps and making basic changes to your MapInfo file by following Dunkelschwamm's guide on creating a mapset for ECWolf.

Global properties - The gameinfo structure

The gameinfo structure in MAPINFO is used to hold a lot of global properties about the game, including menu colours and music, "player classes", and more.

Unless specified, ECWolf will assume the default options of the base game being modded.

As an example, if the following gameinfo structure is put in your mod it will make two changes. It will make menu options blue (which looks ugly, but this is just an example), and disable the Read This! in-game manual:

gameinfo
{
    menufontcolor_label = "DarkBlue"
    drawreadthis = false
}

There are a lot of things that can be tweaked in the gameinfo structure, and you can find out more about them on the ECWolf Wiki's Gameinfo page.

As quoted from AstroCreep:

The Map Translator file or XLAT (no relation to ZDoom’s version) is the file that translates binary format maps into ECWolf’s internal structure.

The XLAT file is important if you add things like new walls, objects, enemies, floors/ceilings, etc. Without it, when ECWolf tries to load the custom elements in your game, it may crash or show errors.

Remember, if you do include a customized XLAT file, that it will need to be referenced in the mapinfo.txt file so that ECWolf can find it.

To do this we take advantage of MAPINFO's gameinfo structure, which can contain a lot of general

For example, if you call your xlat file myxlat.txt and put it inside a folder named /xlat, you'll need to have the following line within the gameinfo structure of your mapinfo.txt:

translator = "xlat/myxlat.txt"

AstroCreep has a detailed guide on how the XLAT file functions and what can be done within it.

The lockdef.txt file is used for creating "locks" for doors, and assigning actors to serve as keys for them.

An example of a lockdef.txt with the basic locks for the doors that require the gold and silver keys in Wolfenstein 3D:

lock 1
{
    GoldKey
}

lock 2
{
    SilverKey
}

This creates locks of value 1 and 2, and attaches them to Decorate actors for the GoldKey and SilverKey. This basically says "The player cannot open doors with lock x unless the player has item y.

A lock of course, has to be attached to a door. To do that, the lock needs to be attached to the XLAT information for the door. Here's the definition in the XLAT for the East/West Gold Key Door:

    trigger 92 //Gold Key Door E/W
    {
        action = "Door_Open";
        arg1 = 16;
        arg2 = 300;
        arg3 = 1;
        playeruse = true;
        monsteruse = true;
        repeatable = true;
        activatenorth = false;
        activatesouth = false;
    }

In amongst the values assigned to the door is a series of "arguments" (arg1, arg2, etc). When it comes to doors, arg3 is used if the door is to be locked. So using arg3 = 1; is the same as saying "This door uses Lock 1", which lockdef.txt says is unlocked if the player has the GoldKey.

ECWolf currently* handles changing the statusbar/HUD through the use of a latchcfg.txt file.

This file allows for the disabling/enabling of elements, their positions on the statusbar, and how many digits to display (such as 2 for ammo, 3 for health).

You can see a detailed guide on what can be included in latchcfg.txt here.

*This might change in the future when a more robust and customizable solution is created.

animdef.txt is a file used to manage animated textures, and textures that change through interaction (In the original Wolfenstein 3D, the example would be the way the elevator switch texture changes when it is activated).

For Wolfenstein 3D, the elevator switch "effect" is created with the following line inside animdef.txt:

switch ELEV1_2 on pic ELEV2_2 tics 0

You can learn how to make use of switches by following AstroCreep's guide on Switch-Activated Doors.

Additionally, ECWolf can have animated walls due to its (at current) partial compatibility with Rise of the Triad. To take advantage of this, the following structure is used:

texture EXAMPLE0
    pic EXAMPLE0 tics 3
    pic EXAMPLE1 tics 3
    pic EXAMPLE2 tics 3
    pic EXAMPLE3 tics 3
    pic EXAMPLE4 tics 3

texture defines the start of the animation block, with the first sprite in the wall's animation declared. This is followed by a block of structure pic TEXTURENAME tics TICNUMBER.
When the wall is shown in game, ECWolf will scroll through each texture in the block, staying on each image for the assigned number of tics.

Here's an example of a simple animated wall deployed in ECWolf:

Animations can also be used for floors and ceilings, to create visuals like flowing water.

ECWolf uses sndinfo.txt to assign names and properties to sounds you might add to your project. A detailed explanation of SNDINFO is available on the ECWolf Wiki.

When a new sound is added to your /sounds folder, you can create a definition for it in the sndinfo.txt file to be able to reference it in your scripting. If we added an explosion sound called EXAMPLE1.wav, we could add the following line to the file:

misc/newexplosion    EXAMPLE1

Then whenever we wanted to use the sound, we can call misc/newexplosion.

Your sound names can be expanded to further organize them. If your mod had a new weapon with new sounds for both when it is collected and when it is fired (We'll call them NEWGPUP.wav and NEWGFIRE.wav), you could have the following:

weapon/newgun/pickup    NEWGPUP
weapon/newgun/attack    NEWGFIRE

Here, we've named the sprites so whenever we want to reference a sound for the gun, we know to start with weapon/newgun. Then, depending on if we want the sound for the pickup or the sound for when the gun is fired, we attach pickup or attack respectively.