X Rebirth Wiki (English)
Space shortcuts
Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 6 Next »

With the Steam Workshop, finding and installing X Rebirth extensions is now easier than ever before. Just browse the extensions in the Workshop, subscribe to an extension that you are interested in, and it will be installed automatically the next time your start X Rebirth. Just make sure you read the description and check for incompatibilities with other subscribed extensions.

Extensions from the Workshop will also be updated automatically when the author submits updated content. To disable an extension on the next game start, just unsubscribe from it, either in-game or on the Steam website.

General publishing rules 

General rules and guidelines:

  • Do not publish extensions that you haven't made yourself, unless you have the author's consent.

  • Similarly, do not publish modifications of other people's extensions (e.g. fixed versions) without the author's consent.

  • Do not publish the same extension multiple times. If you are not sure if an upload worked, check your Workshop items online.

  • If your extension depends on other extensions or if it is potentially incompatible with other extensions, use the description text to warn players.

  • X Rebirth extensions support localisation of name and description, but unfortunately the Steam Workshop does not. The title and description texts of Workshop items should be in English, unless you provide content specifically for a non-English audience. But even then, please make sure that English-speaking players can see from the title and description what the item is about.

Preparation

To publish an extension in the Workshop, you will need:

  • The X Rebirth Tools
  • The folder containing your extension files, including content.xml
  • A preview image file, for example a screenshot (must be either JPG or PNG). We recommend a widescreen format, size 640x360 or larger.

Further requirements:

  • You must have chosen a folder name. When the extension is downloaded or updated from the Workshop, it will be placed in this folder under "X Rebirth\extensions".
    • Most likely you will be uploading directly from X Rebirth\extensions anyway. In that case you already have a folder name.
    • There are several naming restrictions:
      • Only the following characters are allowed in the folder name: a-z 0-9 . _ - and space.
      • The name is lower-case; any upper-case letters will be converted to lower-case automatically.
      • The name cannot be longer than 32 characters.
    • The game can handle multiple Workshop extensions using the same folder name, but there will be errors if a player subscribes to multiple of them simultaneously.
    • If there is a non-Workshop extension with the same folder name, the game will not touch that one, the player will have to resolve the conflict manually.
    • If your folder name is very generic and likely to be used by other extensions as well, consider changing it.
    • If you choose to rename your folder in an update, be aware of all consequences, e.g. don't forget to update your index files.

 

  • All game-relevant files must be stored in X Rebirth catalogs, but the Workshop tool can help you with that.
    • If there are no catalogs in your extension folder, you can use the switch -buildcat to build a catalog automatically.
    • To create catalogs manually you can use the catalog tool, included in X Rebirth Tools.
    • Only these file types will be uploaded: *.cat, *.dat, *.cur, *.txt, *.pdf
    • If your extension has mouse cursor files (*.cur), they must be in the root folder, not in a sub-folder. Sub-folders are not uploaded.

 

  • Notes on content.xml:
    • The value of the [i]id[/i] attribute has no relevance before publishing - it will be replaced with a Workshop-specific ID.
      • You need the attributes name and description in the <content> element. These will be used for the title and description of the published Workshop item.
      • To add line breaks in the description attribute, use &#10; (&#13;&#10; is also possible). \n does not work.
      • Title and description can be changed in the Steam Workshop after publishing.
      • The game displays the current title and description as set in the Steam Workshop, unless content.xml provides localised text for the game language.
      • We recommend not to include the version number in the name.
    • You need a version attribute. The value is the version multiplied by 100, so e.g. to display v2.50 you have to specify version="250".
    • By default, the "author" will be set to your public Steam community name. If you want to override this, set an author attribute in <content>.
    • You can have dependencies on other extensions, but these must already exist in the Workshop. Use the IDs from their content.xml files.
    • You can also have a dependency on the version of X Rebirth (i.e. the minimum required version). This is a dependency without an extension ID.

 

Example for a content.xml to publish a new extension:

<?xml version="1.0" encoding="utf-8" ?>
<!-- My Test Extension v0.10 -->
<content id="totally_unimportant" name="My Test Extension" description="This is just an example." version="10">
  <!-- Requires Workshop item 12345, minimum version 1.00 -->
  <dependency id="ws_12345" version="100" />
  <!-- Requires minimum game version 1.50 -->
  <dependency version="150" />
  <!-- Optional localisation (NOTE: not visible in Steam Workshop, cannot be updated from Workshop website) -->
  <!-- German: -->
  <text language="49" name="Meine Test-Erweiterung" description="Dies ist nur ein Beispiel." />
</content>]

 

Minimalistic example:

<?xml version="1.0" encoding="utf-8" ?>
<content id="" name="Foo" description="Test" version="100">
</content>

Using the Workshop tool

The Workshop tool is contained in the X Rebirth Tools. It's a command-line based tool, we don't have a GUI for it (yet). You'll need a command console to run it, and the easiest way to do it is to "Play" the X Rebirth Tools. This will open the Windows command prompt in the X Rebirth Tools folder, where WorkshopTool.exe is located.

Type WorkshopTool and press Enter. This will give you an overview of the available commands and switches. Don't be afraid, the tool will ask for confirmation before it uploads anything.

Publishing an extension

Important: You have to agree to the Steam Workshop Legal Agreement to upload any item to the Steam Workshop.

Imagine you have prepared an extension in the game's extension folder:

...\steamapps\common\X Rebirth\extensions\my first mod

You have also prepared a preview image (see above). It's called preview.jpg and you have put it in your extension folder ("my first mod"). Notice the lower-case folder name. Now it's time to run the WorkshopTool! Your command line to publish your mod will look like this:

WorkshopTool publish -path "..\X Rebirth\extensions\my first mod" -preview "..\X Rebirth\extensions\my first mod\preview.jpg" -buildcat

[You may also want to use the -tags switch, but tags are not implemented yet. Come back later to see if this has changed.]

You must be logged into Steam while the WorkshopTool is running.

So what is happening now?

  • We are not using the -foldername override switch here, so the WorkshopTool takes the actual folder name: "my first mod" (note that this is a bad name!)
  • We are not using the -contentdef override switch, so the WorkshopTool just takes the content.xml in the "my first mod" folder.
  • Since we haven't bothered to create catalog files manually, we use the -buildcat switch so the WorkshopTool does everything for us.
  • The catalog tool builds ext_01.cat / ext_01.dat, which will be included in the files to be uploaded. These catalog files will be deleted automatically when the WorkshopTool finishes. You can prevent the deletion with the switch [i]-keepcatfiles[/i], but in that case don't forget to update or delete the catalogs manually later!
  • The WorkshopTool validates the metadata in content.xml and shows some output. Please read it all and make sure there are no mistakes.
  • The tool will ask for confirmation: "Start upload to the Steam cloud (y/n)?" Type Y or N, respectively, and press Enter.
  • Just wait for the upload to finish. This can take some time. You can abort the upload with Ctrl+C.
  • When the upload finishes, some XML attributes will be written back to content.xml, most importantly the id attribute, which identifies the extension as a Workshop item.

 

After the successful upload you are asked if you want to open the Workhop item web page. You should do this for several reasons:

  • You may have to confirm the Steam Workshop Legal Agreement online.
  • Even after upload, the Workshop item will not be visible for other players yet. You will have to set the visibility on the Workshop item page (visible for everyone or only for friends)
  • On the item page you can directly change the title and description, without having to update your Workshop item.[/list]

 

If the web page tells you that the Workshop item does not exist, you are probably not logged in. Just log in to see your item.

If you want to come back to the page later, either create a bookmark in your browser, or run the WorkshopTool with the command showpage:

WorkshopTool showpage -path "..\X Rebirth\extensions\my first mod"

Usually, when you subscribe to an extension in the Workshop and start X Rebirth, it will be downloaded, potentially overwriting files from the previous version on the disk. This won't happen for your own extension because the WorkshopTool writes sync="false" into your content.xml after publishing. So you can safely keep your extension in the game folder while working on updates. (However, it's always a good idea to back up your files regularly.) If you want to enable synchronisation anyway, no problem: Go to the extension menu in-game, go to your extension and set "Updates" to "Yes".

A side effect of disabled updates is that X Rebirth will not update the name and description in your local content.xml when you change them on the Steam Workshop page. However, other players will see the updated name and description in their games.

Once players can see your extension in the Workshop, they can subscribe to it, and install it by starting X Rebirth. You disable the extension by unsubscribing from it. If players just delete the folder without unsubscribing, it will be downloaded again on the next game start.

If your extension has dependencies on other Workshop items, players have to subscribe to all of them manually, otherwise they will get an error message in the game. The dependency extensions will be shown in the in-game extension menu and can also be subscribed there.

Updating an extension

For updating an existing Workshop item, your command line could look like this:

WorkshopTool update -path "..\X Rebirth\extensions\my first mod" -buildcat -changenote "This is my first update"

Some things that are different from the publish command:

  • The -changenote switch is required for all updates. Write -changenote "" if you do not want to provide a description. You can also edit the change notes on the Workshop page after updating.
  • The WorkshopTool expects that you have increased the version number. If you deliberately keep the version number in your content.xml unchanged, use the -minor switch.
  • Usually an update does not affect the Workshop title and description. To upload the name and description attributes from content.xml to the Steam Workshop anyway, use the switch "-namedesc up" (without the quotes).
  • Changing the preview file is optional. If you want to change the preview file without uploading new content, use the command updatepreview instead of update.
  • It's possible to change the folder name of the extension. Important: Make sure that you do not do this accidentally, e.g. by uploading from a different folder! The WorkshopTool will show old and new folder names before you confirm the upload. Please check this output carefully.
  • After the upload, a few XML attributes will be written back to content.xml like when publishing, but the sync attribute is not added or changed. So in case you enabled updates after publishing the extension, they won't be disabled again.

When X Rebirth updates an extension, it checks the the downloaded content.xml for a game version requirement. If the extension requires a higher game version, the game discards the download (with a warning message) and continues to use the existing files on the disk. So if you as a Workshop author change the game version requirement, this will not break anyone's game. However, there are no such checks when you change dependencies on other Workshop extensions and their versions - the update will be applied anyway.

  • No labels