Lets put some cogs on fishpeople (modding thread)

Do you like modding? If you said no I don't think we can be friends.


If you like modding do i have great news for you. Clockwork Empire lays nearly everything out in text files for us to get our grubby paws on. Most things are handled with LUA or XML and are surprisingly easy to figure out. It is also extremely powerful since nearly everything that things do in the game are handled by the LUA and XML with the compiled code working as the glue to hold them together.

Did you see MOOMANiBE's tweet?

Not pictured: Nicholas almost suffering a heart attack thinking it was was bug.

I spent a weekend puzzling over the CE files and reading LUA tutorials and made a mod to carve log into a living dodo to see if I had actually figured stuff out. I'm confidant there will be great and terrible things made by the community now that the slug is out of the incubation pod.

I'm starting this thread to share what I've figured out about the game systems and help get those cogs spinning. I'm hardly the authority on this so please point out corrections and suggestions or new things you have figured out. I've also been thinking a bit about the potential snares that could come from mods and will hopefully post ideas to help mitigate them.

CONTENTS

LINKS

 

DON'T REPORT MODS PROBLEMS AS BUGS!
If you break something with a mod don't post a bug report about it. The devs have a ton on their plate right now and while they have been really helpful to me with figuring things out don't make their life harder or think of assistance with mods/understanding files as an unexpected bonus.

BEFORE YOU GET STARTED BACKUP YOUR FILES
Clockwork Empires has been updating very rapidly and Steam will happily delete your hard work. On the other hand if you break something you don't want to wait for Steam validate everything for you. I copied everything I was going to mess with into a CE backup folder in another directory.

Additionally I do all my mod work in another CE mods folder in another directory and then copy them to the main folder when I want to use them in game. If you edit the files in the \Clockwork Empires\ directory when you update any changes will be overwritten by the new files and you will lose your hard work.

The basics of Clockwork Empires modding
Almost tremendous amount of CE is in very accessible files. In Steam\SteamApps\common\Clockwork Empires you will find \Game \Scripts these hold the information about how stuff works in game. There are also \ui textures\ sfx\ models\ music\ and shaders\ which control how things look and sound. I don't do that kind of stuff but it should also be pretty easy to change.

In game\ everything is a .xml file. They have mostly descriptive names but not all of them are actually used. These can be modified in a text editor. Most interesting for modding right now are \game\events\events.xml and the ones in \game\jobs\ Personally I use Notepad++ since its powerful but not intrusive and will do syntax highlighting plus a lot of other useful things.

In scripts\ there are more kinds of files: .lua .edb .go and .fsm. However they are all actually plain text LUA files. Again I use Notepad++ to mess with them and associated it as the default program to open them with. If you open them in Notepad++ you can turn on syntax highlighting from the language menu > L > Lua which makes them quite a bit easier to read.

I didn't know any Lua when I started this but its a pretty easy language to use and you have lots of examples at hand. The Lua.org will tell you more than you ever wanted to know but I found the Lua-users.org tutorials very helpful. Clockwork Empires expands on Lua with a lot of specific tools to do game stuff but the basics are the same.

The Files
Starting with with the game folder the first level is filled with xml files that are used to define some information for number of parts of the game. They mostly have self explanatory names, Commodities.xml is (I think) the information about what goes in the Commodities menu in game, their icon, tooltip and how they are filtered. Some of these files don't seem to be used or are placeholders for things to come or leftovers of things that have been moved to other files.

There are a couple very interesting files here though. Namely \events\events.xml and the ones in \jobs\. Events.xml gives important information about how events happen to the engine. For example immigrants are handled by

Code:

  <event name="Immigration">
  <require_timer name="Immigration Timer" value="4500"/>
  <script name="immigration"/>
  </event>

This references other files so the engine knows how to use them. Similarly the various jobs xmls give the glue ties together the different parts of a job. There are helpful but somewhat outdated and sparse documentation in these files.

The scripts folder is where we get into the meat of things. Despite the different file names everything in here is actually a plain text Lua file. The .lua files in the \scripts\ folder are pretty complicated and define things like how the other files are handled. In theory you could do very weird things that change how everything is run, but that way lies madness.

Moving on to the entity folder. This folder contains .edb (Entity DataBase ?) files that define important details about entities. The details of your colonists are in citizens.edb and you find such information as what makes a common laborer and an aristocrat

Code:

Entity {
   name = "Labourer",
   type = "citizen",
   socialClass="lower",
   military=0,
  iconName="labourers_icon",
  iconSkin="orderIcons.xml"
}

Entity {
   name = "Aristocrat",
   type = "citizen",
   socialClass="upper",
   military=0,
  iconName="upper_class",
  iconSkin="thoughtIcons.xml"
}

But it also has global information about all citizens

Code:

Entity {
   name="HumanStats",
   type="stats",
   numAfflictionsToDie=3,
   corpseRotTimeDays=2,
   starvationHungerDays=3,
   sleepTirednessRecoverySeconds=600,
   tirednessMaxSeconds=600,
   idealAwakeToSleepRatio=5,
   idealSleepTimeSeconds=90,
   healthMax=10,
   healthRegenTimerSeconds=8,
   tags = { "human", "humanoidSized", "tool_use" , "hat_use" , "character", "combat_target_for_enemy", "character", "conversable", "phrenology_unknown" }
}

Two important things to note here. First you can have different types of entities in the same edb file (both citizen and stats) and second the entity type doesn't have to go in the file of the same name. I expected everything to be in the .edb for its type but ClearableTerrain.edb has explosions (which there is no matching explosions.edb), objectclusters (and ObjectClusters.edb is empty), and clearables. Some digging will turn up a third thing that the same entity type can be in different edb files. Citizens.edb and world.edb both have entries of type stats and they have different properties.

If you have looked over Lua already these entities might look an a bit like tables. That's not a coincidence. The game will serve these entities up to you in other places as a table with the members as defined here. As in HumanStats a member may also be a table (tags in this case). The syntax is a bit different from an actual Lua tables though, just to throw you off.

In \scripts\gameobjects\ we see the .go scripts for the various objects in the game. We saw that there are citizens defined in citizens.edb (specifically those with type="citizen") well citizen.go tells the game what those do. Citizens are complicated so there is a lot in citizen.go. I'm only going to touch the basics. First at the top you see

Code:

gameobject "citizen" inherit "ai_damage"
<<
   local
   <<

And a ways down (line 501 in in the version 27B citizen.go) is

Code:

  >>

   state
   <<
     gameAIAttributes AI
     string vocalID
     string animSet
     int renderHandle
     string descriptiveParagraph
     string seat
     bool release
   >>

   receive Create( stringstringMapHandle init )
   <<

 

and another reserved

 

Maybe we will need three?

 

Modding a pre-release game is of course fraught with danger. But we laugh in the face of danger because we have seen what is no meant to be seen!

And I choose to take the fact that encountering broken code isn't a certainty as encouragement!

 

The optimism in this thread is awesome. Tagging to watch for updates.

 

While I feel it's a bit too early to mess with things, I do have an idea...

Rimbaud's Army - All your colonists are poets and laudanum fiends.... you're never quite sure who is a soldier and who is a fishman.

 

I've been tearing apart XML files since CNC Generals, and tearing apart LUA files since Star Wars: Empire at War. Both of those were riddled with broken code, in a complete and finished project. I say: BRING IT ON!

 

It could be a lot worse, the code could be obfuscated. I still don't know how people moded Minecraft without going insane.

 

A quick look-see revealed the following:

Models: are in *.upm and *.upa. I am assuming the UPA refers to animations, but I am not familiar with either of those files.
Music: is in *.ogg format, easy enough to edit and create
Sounds: are in the SFX folder and are in *.wav, extremely easy to create and edit.
Textures: are in *.png and *.tga. TGAs are a little more difficult to edit than PNGs, but both are very accessible.
User Interface: appears to be a combination of XML and PNGs

 

Just a very quick shot showing just how accessible this game is for modding so far.


We might not want to butcher this particular animal....

 

Sorry for the double-post, but one more quick example of how modding can be done. Still working my mind around the icons, so I had to borrow one from something else for the moment. But still!

 

Haha awesome.

If you want to put in details for how you did those / explanations of those parts I would be thrilled and link them. I don't know anything about graphics or UI (I did see the traits and would eventually get around to documenting them) stuff so someone else is going to have to explain that.

 

Of course! As you mentioned, under clockwork empire\game there is a file named traits.xml. It's one of the more straightforward files I've seen yet. Here's a copy of the original code, and here's the code I put in myself:

First: HUGE SPOILER WARNING!!

Don't go digging around in the textures, icons or model sections if you don't want certain "Fun Things" ruined for you!!

Code:

  <trait name="Adventurous" displayName="Adventurous" icon_skin="ui\thoughtIcons.xml" icon="map">
    <description text="This character gains a happiness benefit from exploring, and from doing different jobs; all jobs classified as 'exploration' will receive a happiness boost."
    phrase="enjoys trying new things and boldly exploring where no one has gone before."
    clause="exploration and new experiences" />
  </trait>

That's what I used as my base, and then simply replaced it with my own, like so:

Code:

  <trait name="Other Imperialist" displayName="Other Imperialist" icon_skin="ui\thoughtIcons.xml" icon="heart">
    <description text="This Character is rooting for The Empire, but you get the distinct impression it's a very Different Empire. They speak of Siths and Vader and you simply smile and wave."
    phrase="enjoys fine dining and the Sith Arts."
    clause="is looking for the Rebel Base" />
  </trait>

I'm not entirely certain what the "phrase" and "clause" parts of the code are referring to yet, but I'm digging. I think they might be "tags" that the game creates which causes these things to happen. You see in "Adventurous" that the clause is "exploration and new experiences" so maybe those are tags that the game itself puts out and checks to see if anyone reacts. Not sure yet.

You'll notice that for the icon, I chose "heart," which was something mentioned by the Trait "Romantic Inclination." Also, in the code itself you'll notice "ui\thoughtIcons.xml" listed. Looking at that file again I think I can figure out what it's talking about, but under the spoiler is some of the code for it.

Spoiler

Code:

<element name="image"  scale="exact">

    <state name="job_icon_holder32" x="817" y="956" w="50" h="66" />
    <state name="machine_thought32" x="867" y="956" w="50" h="66" />
    <state name="thought_bubble32"  x="971" y="956" w="50" h="66" />
    <state name="speech_bubble32"   x="919" y="956" w="50" h="66" />

    <state name="job_icon_holder" x="489" y="911" w="82" h="110" />
    <state name="machine_thought" x="571" y="911" w="82" h="110" />
    <state name="thought_bubble"  x="653" y="911" w="82" h="110" />
    <state name="speech_bubble"   x="735" y="911" w="82" h="110" />

    <state name="job_icon_holder64" x="489" y="911" w="82" h="110" />
    <state name="machine_thought64" x="571" y="911" w="82" h="110" />
    <state name="thought_bubble64"  x="653" y="911" w="82" h="110" />
    <state name="speech_bubble64"   x="735" y="911" w="82" h="110" />
<!-- start row 1 -->
  <state name="cloud_rain" w="64" h="64" x="0" y="0" />
  <state name="cloud_lightning" w="64" h="64" x="64" y="0" />
  <state name="sun_smiling" w="64" h="64" x="128" y="0" />
  <state name="sun" w="64" h="64" x="192" y="0" />
  <state name="fist_upheld" w="64" h="64" x="256" y="0" />
  <state name="questionmark" w="64" h="64" x="320" y="0" /> -->

I'm still trying to decipher that one, but I'm pretty sure the numbers are referring to a specific location in the file \ui\icons\thoughtIcons00.png, which looks a little like this:

Spoiler

As you can see in that image I uploaded, I simply put an Imperial symbol over the Heart symbol because I hadn't yet figured out the way the thoughtIcons.xml file was referring to locations. Now that I've looked at it again, it appears that "Start Row One" is referring to the top row, with the w="64" h="64" referring to the icon's size in-game, and the x="0" y="0" referring to its location in that row. This bears out in the following stages, so once you find an icon you want (or create a new one in all the blank spaces, or better yet create a blank thoughtIcons01.png) you mention what it's size is and where in the target file it is located.

I'm not entirely certain if any of that made any sense. I hope so!

Edit: I've done some more experimenting and it turns out that my hunch about the locations is correct. I will be writing up a more comprehensive "how-to" on how to change, or link, or even create, Icons in a little bit.

Double Edit: Having computer issues, I'll get to it later tonight

 

Haha, nice work guys. I also intend to mod the living daylights out of this game on (or even before) release.

I've started working through some of the lua files in order to compile a list of engine commands currently being used. While I realise the codebase might change drastically before release, I reckon that the engine is pretty much bedded down now that they are focussing on gameplay in scripting etc. So perhaps a few parameters and ordering might change but I can't imagine the engine manager classes being too volatile.

Anyway, might become useful later on when modding in anger.

Example :

Code:

Notes: not sure if the gameObject "handle" is int:goHandleId or should actually be ctype[gameObjectHandle]...


COMMTYPE    ENGINEMANAGER                        ENGINECOMMAND                                    EXTRAPARAMS|

send        rendCommandManager                    odinRendererEventAlertMessage
send        rendCommandManager                    odinRendererCreateParticleSystemMessage
send        rendCommandManager                    odinRendererSetLighting
send        rendCommandManager                    odinRendererTickerMessage                        string:tickerMessageText|string:iconName|string:iconXMLFilePath
send         rendCommandManager                    odinRendererAlertMessage                        string:iconXMLFilePath|string:iconName|string:alertTitle|string:alertMessageText|string:iconHoverText

send         rendStaticPropClassHandler            odinRendererRotateStaticProp                    int:goHandleId|int:angleinDegs(0, 359)|float:value?  
send        rendStaticPropClassHandler            odinRendererDeleteStaticProp
send        rendStaticPropClassHandler            odinRendererCreateStaticPropRequest
send        rendStaticPropClassHandler            odinRendererStaticPropExpressionMessage            int:goHandleId|string:attribName|string:attribText
send        rendStaticPropClassHandler            odinRendererIdleCharacterMessage

send         rendOdinCharacterClassHandler        odinRendererSetDescriptionParagraph                int:goHandleId|string:paragraphText
send         rendOdinCharacterClassHandler        odinRendererFaceCharacter
send         rendOdinCharacterClassHandler        odinRendererSetCharacterWalkTicks
send         rendOdinCharacterClassHandler        odinRendererSetCharacterAttributeMessage        state.renderHandle, "health", "Excellent Health");
send         rendOdinCharacterClassHandler        odinRendererTeleportCharacterMessage
send         rendOdinCharacterClassHandler        odinRendererSetCitizenPathMessage
send         rendOdinCharacterClassHandler        odinRendererMoveCharacterMessage

send         rendInteractiveObjectClassHandler    odinRendererBindTooltip
send         rendInteractiveObjectClassHandler    odinRendererAddInteractions
send         rendInteractiveObjectClassHandler    odinRendererClearInteractions
send        rendInteractiveObjectClassHandler    odinRendererPlaySFXOnInteractive

send        scriptUIManager                        createSelectionDialogBox

query        scriptManager                        scriptCreateGameObjectRequest                    string:goName|table:{legacyString = string:goType}

send        gameSession                            incSessionInt
send        gameSession                            spawnEvent  
send        gameSession                            setSessionInt
send        gameSession                            setSessionBool
query        gameSession                            getSessionInt
query        gameSession                            getSessionBool

query        gameObjectManager                    gameObjectCollectionRequest                        string:goName

send        int:goHandleId                        GameObjectPlace                                    int:gridLocX|int:gridLocY
send        int:goHandleId                        SleepMessage                                    NONE
send        int:goHandleId                        setGrowthStage
send        int:goHandleId                        resetRendering
send        int:goHandleId                        growthPing
query        int:goHandleId                        gridReportPosition
query        int:goHandleId                        getAIAttributes
query        int:goHandleId                        resetInteractions
send        int:goHandleId                        ViralJobPropagationMessage

send        gameSpatialDictionary                registerSpatialMapString
send         gameSpatialDictionary                gridRemoveObject
send         gameSpatialDictionary                gridSetPlayerSpawnPoint                            ctype[gameGridPosition]:gridPosObject|int:radiusValue
send         gameSpatialDictionary                gridExploreFogOfWar                                int:gridLocX|int:gridLocY|int:radiusValue
send        gameSpatialDictionary                gridAddObjectTo
send         gameSpatialDictionary                gridDeclareMoveObjectTo
query         gameSpatialDictionary                gridGenPathToPosition
query        gameSpatialDictionary                gridCanAddObjectTo                                int:goHandleId|ctype[gameGridPosition]:gridPosObject
query        gameSpatialDictionary                gridGetObjectCenter
query        gameSpatialDictionary                nearbyEmptyGridSquare                            ctype[gameGridPosition]:gridPosObject|int:radiusValue
query        gameSpatialDictionary                nearbyEmptyAreaNear                                ctype[gameGridPosition]:gridPosObject|ctype[gameObject]:SELF
query        gameSpatialDictionary                allObjectsInRadiusRequest

query        gameBlackboard                        gameObjectNewAssignmentMessage
send        gameBlackboard                        gamePositionNewJobToAssignment
send        gameBlackboard                        gameObjectNewJobToAssignment
send        gameBlackboard                        gameAgentJobCompleteMessage
send         gameBlackboard                        gameObjectRemoveTargetingJobs

 

Here's a bit more of an explanation of what I accomplished yesterday, now that my internet is back to working (mostly.)

When looking at traits.xml, I noticed this particular line:

<trait name="Adventurous" displayName="Adventurous" icon_skin="ui\thoughtIcons.xml" icon="map">

When looking at commodities.xml, I saw this line: <display skin="ui\commodityIcons.xml" icon="icon_blunderbuss"/>

That means the User Interface (conveniently in the /ui folder) is organized in the XML files, in this case thoughtIcons.xml and commodityIcons.xml

Both XML files use an X/Y format that points to a PNG file. I'll be using the thoughtIcons one as my example. Here's the code of the first few icons.

Code:

<skin name="Thought and Emotion icons" texture="ui/icons/thoughtIcons00.png">
<!--///a bunch of other code\\\ -->
<!-- start row 1 -->
  <state name="cloud_rain" w="64" h="64"         x="0" y="0" />
  <state name="cloud_lightning" w="64" h="64"     x="64" y="0" />
  <state name="sun_smiling" w="64" h="64"         x="128" y="0" />
<!--///a bunch of other code\\\ -->
  <state name="map" w="64" h="64" x="640" y="64" />

We can now look at the file I just created as a reference.

Spoiler

The game itself points to the XML file (icon_skin="ui\thoughtIcons.xml" icon="map"). You look in the XML file for
"map" and you'll find <state name="map" w="64" h="64" x="640" y="64" />. The state name is the name of the icon that traits.xml refers to (icon="map"), the code w="64" h="64" refers to the size of the icon (most of them except the thought bubbles are 64x64), and the code x="640" y="64" refers to where the icon "map" shows up in thoughtIcons00.png. Once you get the grid layout figured out, it becomes very easy to make your own.

How to make your own icons and traits
As Dienes mentioned at the beginning, always make backups. It's just smart. The best way to check and make sure that your changes are taking place in a file like traits.xml is to remove everything but what you changed. Here's the code I used for my tests:

Code:

<traits>

  <trait name="Sith Imperialist" displayName="Sith Imperialist" icon_skin="ui\thoughtIcons2.xml" icon="sith_empire">
    <description text="This Character is rooting for The Empire, but you get the distinct impression it's a very Different Empire. They speak of Siths and the Dark Side and you simply smile and wave."
    phrase="enjoys fine dining and the Sith Arts."
    clause="is looking for Revenge" />
  </trait>

  <trait name="Killer Clan" displayName="Killer Clan" icon_skin="ui\thoughtIcons2.xml" icon="mandalorian">
    <description text="This character likes to kill things. Everyone he is partially related to likes to kill things. Something about Honor and Glory and -oh wait, you're dead already."
    phrase="Battle is for HONOR and GLORY and lots and lots of blood."
    clause="battle" />
  </trait>

  <trait name="Republican" displayName="Republican" icon_skin="ui\thoughtIcons2.xml" icon="old_republic">
    <description text="This character believes in the strength of the Jedi Knights and the power of the Force to control and protect all life. They will probably quote long speeches to you instead of doing anything worthwhile."
    phrase="Battle is for HONOR and GLORY and lots and lots of blood."
    clause="is self-righteous" />
  </trait>

</traits>

(we can ignore "phrase" and "clause" right now because I haven't dug through them yet)
You'll notice that I changed icon_skin="ui\thoughtIcons2.xml" icon="sith_empire"(and the others have different names too) I created a second thoughtIcons.xml file and named it thoughtIcons2.xml, keeping just the basic code; once again, keeping only the code that I needed for this test. So the traits.xml points to the thoughtIcons2.xml file, calling for an icon with the name sith_empire.

So let's go look at thoughtIcons2.xml!

Code:

<skin name="Thought and Emotion icons" texture="ui/icons/thoughtIcons01.png">

  <element name="image"  scale="exact">

<!-- start row 1 -->
  <state name="old_republic" w="64" h="64" x="0" y="0" />
  <state name="mandalorian" w="64" h="64" x="64" y="0" />
  <state name="sith_empire" w="64" h="64" x="128" y="0" />

    </element>

</skin>

The skin and element parts are necessary part of the XML coding file and should be left alone. However, we now see that in the thoughtIcons2.xml file, there is indeed a name "sith_empire." It has a width and height of 64, as is standard, and it's location is x="128" y="0". Looking at the thoughtIcons.png file I put above, that location would give us a smiling sun! The Sith Empire can't have a smiling sun as its logo! That would be blasphemous! ...or darkly ironic, perhaps. However, those with sharp eyes will notice that in the code for thoughtIcons2.xml, the part at the top: <skin name="Thought and Emotion icons" texture="ui/icons/thoughtIcons01.png"> I changed "ui/icons/thoughtIcons01.png". The original thoughtIcons.xml file points to a file called thoughtIcons00.png. So I went and created a thoughtIcons01.png. And here's what it looks like:

Spoiler

It's filled with much less icons than 00.png, as befits the idea that I'm doing only what I include. Looking at our grid, x="128" y="0" now points the much more appropriate Sith Empire logo.

I did the same with the other two icons, and here are the in-game results:

Spoiler

You'll notice that the first and third colonist is part of two very difficult cultures, but that's okay because I put these in as Traits and not as countries-of-origin. That's my next attempt to figure out, but for now, we have 3 new traits and 3 new icons to go with them!

Feel free to use any of the code or icons I put up here for your own use.

 

Awesome. I meant to do that at some point but hadn't gotten around to it yet. I'll try and get more info posted about the ones I know how to use and the rest of the game files when I get a chance.

I know some of the game files have old code that might no longer work since some stuff has been around for a long time and the engine has changed. Still I think you are right that we probably won't see the engine turned upside down since trying would probably end up with Nicholas or Micah killing each other.

 

https://dl.dropboxusercontent.com/u/26484985/CE_engine_comms.txt

Ok cool, well I'll just keep a running WIP file in Dropbox for reference as I build it up.

If I get some time I'll start compiling some of the static DB values that are referenced in the code. Things like EntityDB table strings, VALUE_STORE table strings, gameSession attributes etc. Those vars might be a lot more volatile so might wait a bit until I compile a list or write some scripts to pull them out.