Fractal Softworks Forum

Starsector => Mods => Modding Resources => Topic started by: Alex on May 14, 2011, 11:46:37 AM

Title: Mod Format Preview
Post by: Alex on May 14, 2011, 11:46:37 AM
Update - working with version 0.35a

To get mods to work with the 0.35a preview release, add "gameVersion":"0.35a" to the descriptor. And actually make sure the mod works, too. The main issue is some stock ship variants have different ids now, and if your mod was using those, it'll need to be updated with the new ids.

Another issue is a bug with the CSV loader - it won't handle quotes correctly in the first row. - this is fixed in RC2, which is now out.

Overview

Mods can either modify existing entities (ships, weapons, missions, etc) or add entirely new ones.

The directory structure of a mod mirrors that of the game itself. In addition, each mod has a mod_info.json file at the top level which specifies its id, display name, version, and a brief description.

You can look at a mod as being a copy of the game, but containing only the parts that are different from the vanilla version.

Example Mods

Some simple mod examples to get you started:


Note on Adding Ships/Weapons/etc (Important!)

Anything your mod adds (a ship, a ship variant, a weapon, a mission, etc) has an id. Please use a prefix specific to your mod for these ids. For instance, in the 2nd example mod, you'll notice that the new ship's id is "ex2_red_tempest", with "ex2_" being the mod-specific prefix.

Also, put graphics your mod adds in a separate directory. If your mod name is "my_mod", you could put your ships under graphic/my_mod/ships, weapons under graphics/my_mod/weapons, etc.

If you don't do this, other mods and future versions of the game might have unintentional conflicts with your mod. That would be very, very bad.

Note: DO NOT put weapon and ship data files in a different directory. The game expects to find those under data/weapons and data/ships respectively, and these already have IDs to help tell apart. Multiple mods having the same filename for a weapon/ship is fine as long as the ids are different (see first point above).

Installing Mods

To install a mod, download it and unzip it into the "mods" directory. On Windows, it's in the installation directory. On Mac, it's right inside the application package - right-click on the application and select "Show Package Contents" to see it. On Linux, it's in the starfarer directory.

You can select which mod(s) you want to run with in the launcher.
Title: Re: Mod Format Preview
Post by: mecharm on May 14, 2011, 11:50:34 AM
Awesome, thank you! :)
Title: Re: Mod Format Preview
Post by: SeaBee on May 14, 2011, 02:55:36 PM
Joyous! This is awesome. The mods for this game are going to be unbelievable.
Title: Re: Mod Format Preview
Post by: Avan on May 14, 2011, 04:24:57 PM
Cool - now just to port everything over. Shouldn't be difficult at all to do.
Title: Re: Mod Format Preview
Post by: Alex on May 15, 2011, 11:10:15 AM
Joyous! This is awesome. The mods for this game are going to be unbelievable.

If stuff that's already been done is any indication, I'm inclined to agree :)

Cool - now just to port everything over. Shouldn't be difficult at all to do.

Speaking of that... seriously looking forward to actually being able to fly around in your ships!

Title: Re: Mod Format Preview
Post by: BlacKcuD on May 18, 2011, 01:19:31 PM
This is so awesome! I will create like the biggest capital ship ever :)
Title: Re: Mod Format Preview
Post by: Apokus on May 19, 2011, 09:32:16 AM
Woa, great news! :)
Good that i couldnt work on my little mod the last days (who the hell gets a flu while we have 25°C outside? -.-) ^^
Not thaaat much more to port into the new system this way :)

Btw, read about the
Quote
Improved spreadsheet loading code - should be able to handle CSV files saved with OpenOffice etc
... does that work with all versions (mean : UTF-8) or only the "normal" US/UK Settings @ open office? ^^
Title: Re: Mod Format Preview
Post by: Alex on May 19, 2011, 11:33:22 AM
Btw, read about the
Quote
Improved spreadsheet loading code - should be able to handle CSV files saved with OpenOffice etc
... does that work with all versions (mean : UTF-8) or only the "normal" US/UK Settings @ open office? ^^

Just UTF-8, actually. If you use standard ascii stuff it won't matter much what you save it as (as long as you don't do something silly like UTF-16), but if you use any special characters make sure to save as UTF-8.

Edit: If you use any special characters, also expect it to not work. Most of the "standard" western ones (letters with accents etc) are supported by the fonts, but the vast majority of the UTF-8 set is not.
Title: Re: Mod Format Preview
Post by: Apokus on May 19, 2011, 01:00:09 PM
Unicode (UTF-8) is great :)
Title: Re: Mod Format Preview
Post by: baxmau on May 19, 2011, 11:41:42 PM
Alex: Do you have any plans to release the ship editor any time soon? I'm tempted to just write my own (thanks for JSON format btw :) )
Title: Re: Mod Format Preview
Post by: Alex on May 20, 2011, 09:05:59 AM
Alex: Do you have any plans to release the ship editor any time soon? I'm tempted to just write my own (thanks for JSON format btw :) )

I think around the same time or a bit after 0.35a - the release which has the ship refit screen. Once that's in place, I'll feel comfortable that the ship file format won't need to change much, and we can release the editor and "officially" support ship modding.

Still need to tweak the editor, too - it has some UI quirks, and uses an intermediate file format (which it then exports into .ship files). I don't remember if there's any reason left for the intermediate format, might just take it out.
Title: Re: Mod Format Preview
Post by: TheDeceit on May 30, 2011, 03:23:10 PM
This sounds great, Alex.  Can't wait to give it a go.   :)
Title: Re: Mod Format Preview
Post by: Hamster on June 04, 2011, 05:03:33 PM
Oh dear god this is incredible.

<3
Title: Re: Mod Format Preview
Post by: majormauser on June 10, 2011, 01:59:03 PM
Mods already! I remember the days we had to wait for mods.

Thanks for 34! and especially the Mods addition that was a surprise and a gift.
Title: Re: Mod Format Preview
Post by: Avan on August 19, 2011, 08:33:43 PM
Any specific notes on changes in .35a-pre?
Title: Re: Mod Format Preview
Post by: Alex on August 20, 2011, 08:19:56 AM
Any specific notes on changes in .35a-pre?

See the "modding" section in the patch notes :)
Title: Re: Mod Format Preview
Post by: Avan on August 20, 2011, 09:02:35 AM
I was mostly asking in terms of broken compatibility, like the missing JSON objects ("mission", "ID"), etc.
Title: Re: Mod Format Preview
Post by: Alex on August 20, 2011, 09:13:25 AM
I was mostly asking in terms of broken compatibility, like the missing JSON objects ("mission", "ID"), etc.

All the stuff of that nature that I was aware of would be there. Which apparently isn't all of it.

"ID", also?
Title: Re: Mod Format Preview
Post by: Avan on August 20, 2011, 09:29:22 AM
Yeah, I found that when I disabled the missions, leaving only the ships and weapons.
Title: Re: Mod Format Preview
Post by: Salient on August 21, 2011, 01:38:36 PM
Please update your examples, they dont seem to work with the latest release.
Title: Re: Mod Format Preview
Post by: Salient on August 21, 2011, 01:45:28 PM
After reinstalling the latest release, i try to load up example 2, and the new ship doesn't appear in the list of enemy ships, and an error is displayed in the mission description 'Ship Hull Variant not found'
Title: Re: Mod Format Preview
Post by: Alex on August 21, 2011, 01:49:50 PM
When did you grab the example? I updated them sometime yesterday, and it's working on my end now.

In either case, my apologies - I kind of forgot about those until just after the release.
Title: Re: Mod Format Preview
Post by: Wyvern on September 26, 2011, 10:06:17 PM
I'm playing on a mac, and there are a couple of issues I've been having with the second example mod.

First one worked fine.

Trying to install a second one... I had to move the first out of the way; the game refuses to recognize that a mod is installed unless its files sit at the root level of the mods folder.  I.E. if I have mods/example1/mod_info.json and mods/example1/data/... - the game says I have no mods installed; I have to have mods/mod_info.json and mods/data/...  Which means I get to have one mod available at a time.  This seems like it might not be intended behavior.

And then, when I actually try to play the mission in example2, I just get a black screen when I ought to be deploying ships.  Clicking just makes the game beep at me.  Hitting escape makes the game immediately quit.
After some effort, I tracked it down to the mission's descriptor.json file - apparently "background":"graphics/backgrounds/background4.jpg" was not something the game was at all happy with; changing it to background1.jpg (to match the mission in example one) fixed the problem.
Title: Re: Mod Format Preview
Post by: Alex on September 27, 2011, 08:38:14 AM
Thanks for reporting these! I don't know how you even managed to figure it all out :)

Updated the 2nd example mod to use a valid background. The mods problem is a bug/typo in the app bundle - if you like, you can actually tweak it and make it work in your version. To do that, open up Starfarer.app/Contents/Info.plist and change
-Dcom.fs.starfarer.settings.paths.mods=../../..
to
-Dcom.fs.starfarer.settings.paths.mods=../../../mods
Title: Re: Mod Format Preview
Post by: Wyvern on September 27, 2011, 12:12:09 PM
Ooh, nice.  I shall do that, then; thanks.

(I'd discovered the "solution" by just not being sure if I was supposed to put the example1 folder in mods, or the contents of example1 in mods - I've had issues with other things that said "put contents of zip file in XYZ", but came out of being zipped with an extra layer of folder that wasn't supposed to be there.  So that was mostly just dumb luck.  The second, though, was persistence: I had a working mission, and a non-working mission, and just started cutting out differences until I found where the problem was.)

And now, on to trying my hand at making a ship!  Whee!  Well... "ship".  With quotes.  Because obviously the game needs space dragons.  ;-)
Title: Re: Mod Format Preview
Post by: Alex on September 27, 2011, 02:05:25 PM
And now, on to trying my hand at making a ship!  Whee!  Well... "ship".  With quotes.  Because obviously the game needs space dragons.  ;-)

It obviously does :)
Title: Re: Mod Format Preview
Post by: Emeraldelite4 on January 24, 2012, 07:24:16 PM
I still need some help installing mods, when you say add "gameVersion":"0.35a" to the descriptor do you mean the mission descriptor file? Or am I not finding a another descriptor file?
Title: Re: Mod Format Preview
Post by: Ivaylo on January 25, 2012, 01:27:07 AM
And now, on to trying my hand at making a ship!  Whee!  Well... "ship".  With quotes.  Because obviously the game needs space dragons.  ;-)

It obviously does :)

Don't forget space crystals. And amoebas.
Title: Re: Mod Format Preview
Post by: Kilvanya on January 25, 2012, 06:44:04 AM
moon butterflies?
Title: Re: Mod Format Preview
Post by: icepick37 on January 31, 2012, 09:22:48 AM
I'm actually going to try and make ships based on insect profiles, haha. Like the Luna moth. Which is pretty close to a moon butterfly.  :)

Silly Jesse...
Title: Re: Mod Format Preview
Post by: Kilvanya on January 31, 2012, 09:34:05 AM
I'm gonna make "The Crystal Ship"

gimme a wink if you know the series it's from
Title: Re: Mod Format Preview
Post by: icepick37 on January 31, 2012, 09:55:45 AM
Starcon?
Title: Re: Mod Format Preview
Post by: Prof_Omnom on February 01, 2012, 06:08:16 PM
I will enjoy playing as a Super-Destroyer, thank you!
Title: Re: Mod Format Preview
Post by: Catattack998 on February 22, 2012, 03:39:43 PM
Is this going to be updated for 0.5a, or are we waiting for the next release? (Yes, I do know that the next release is soon, but I was just checking)
Title: Re: Mod Format Preview
Post by: Alex on February 22, 2012, 05:20:42 PM
#2. Since the preferred way to add stuff via mods is currently broken due to a bug :)
Title: Re: Mod Format Preview
Post by: medikohl on February 23, 2012, 07:07:44 PM
(http://i.imgur.com/6Ecdc.gif)SPACE HAM!

Title: Re: Mod Format Preview
Post by: The Soldier on May 01, 2012, 02:46:16 PM
Will an updated mod version be here for .52a?
Title: Re: Mod Format Preview
Post by: sdmike1 on May 15, 2012, 07:56:08 AM
Question, would it be possible (or even legal?) to post files that are meant to be added/replace files in the starfarer core directory.  Essentially what I am asking here is it possible/allowable to make/post mods that add completely new features to the game that were not there before?
Title: Re: Mod Format Preview
Post by: Alex on May 15, 2012, 08:13:21 AM
Question, would it be possible (or even legal?) to post files that are meant to be added/replace files in the starfarer core directory.  Essentially what I am asking here is it possible/allowable to make/post mods that add completely new features to the game that were not there before?

I'd rather you didn't. That would require decompiling the source (and, while that's possible, there are some measures in places to make that more complicated, and it isn't something I can/will endorse for legal reasons). Also, any such mod would break horribly on every new version release. Horribly.
Title: Re: Mod Format Preview
Post by: sdmike1 on May 15, 2012, 09:04:21 AM
Thanks Just wondering   ;D
Title: Re: Mod Format Preview
Post by: Sendrien on August 21, 2012, 01:22:42 PM
Quick question - is it possible/are we allowed to make a mod that both: a) adds new ships to the Starfarer campaign and b) modifies existing ships?

If the answer is yes, can this be achieved by only reproducing files that changed from the plain vanilla version of the game in the mod folder (my understanding of the original post), or do all the plain vanilla files have to be placed there?
Title: Re: Mod Format Preview
Post by: Trylobot on August 21, 2012, 03:27:28 PM
Only the files that change need to be included in the mod.

If you want to override a vanilla ship's hull, put your new *.ship file in your mod with the same exact file name and ship hullId. If you want to alter its stats, copy its CSV data into a new CSV file structured the same but with only those rows you want to override, with your new values in it.

Additional ships you include in the mod which don't overwrite anything will also be added to the game content.
Title: Re: Mod Format Preview
Post by: Sendrien on August 21, 2012, 07:56:46 PM
Many thanks for this info! It has helped me greatly!
Title: Re: Mod Format Preview
Post by: lechibang on September 21, 2017, 09:05:53 PM
What's the structure for the current version? This article hasn't been updated for quite some time