Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[LazyWizard]

Console Commands
An unofficial developer's console
Download latest dev (requires LazyLib 2.8b and Starsector 0.97a or higher!)
View Javadoc
View progress and source code on GitHub
Archive of old versions
Supports Version Checker

Spoiler

[close]

Instructions
This is installed just like any regular mod. Put it in the mods folder and make sure it's tagged in Starsector's launcher. Once in the game, you can summon the console with control+backspace and enter your commands. While the commands themselves aren't case sensitive, arguments are. For a full list of supported commands enter 'help' in the console. For more information on a specific command use 'help <command>'.

You can enter multiple commands by separating them with a semicolon. For example, "god;nocooldown;reveal;infiniteflux;infiniteammo" would run all of these combat cheats in a row. RunCode is an exception and can't be used with the command separator.

If you want to change the key that summons the console or the command separator, you can change these and several other console settings by using the "settings" command during a campaign.


Known bugs:

• Sometimes the game will crash when opening the console at very high resolutions. You can fix this by disabling the console's background: open saves/common/config/lw_console_settings.json.data in a program like Notepad and change "showBackground" to false. This should happen automatically after a crash.

Current features:

• Input commands using a custom overlay
• A large list of included commands, and the ability to add your own custom commands to the console
• Write, compile and run code in-game using the Janino library
• Doesn't require a new game, and can be safely untagged from a running game without issues
• Should be compatible with all mods, even total conversions

Included commands:

Spoiler

Universal commands (13):

• Alias, BugReport, Clear, DevMode, DumpHeap, Help, List, ModInfo, Reload, RunCode, Settings, SourceOf, Status

Campaign commands (49):

• AddCredits, AddCrew, AddFuel, AddHullmod, AddItem, AddMarines, AddOfficer, AddOrdnancePoints, AddShip, AddSkillPoints, AddSpecial, AddSupplies, AddWeapon, AddWing, AddXP, AdjustRelation, AllBlueprints, AllCommodities, AllHullmods, AllHulls, AllWeapons, AllWings, FactionInfo, FindItem, FindShip, ForceDismissDialog, ForceMarketUpdate, GoTo, Hide, Home, InfiniteFuel, InfiniteSupplies, Jump, Kill, List, OpenMarket, PlanetList, Repair, Respec, Reveal, SetCommission, SetHome, SetRelation, ShowLoc, SpawnDerelict, SpawnFleet, Storage, Suicide, Survey

Combat commands (23):

• AddCommandPoints, BlockRetreat, EndCombat, Flameout, ForceDeployAll, God, InfiniteAmmo, InfiniteCR, InfiniteFlux, Kill, NoCooldown, Nuke, RemoveHulks, Repair, Reveal, Rout, ShowAI, ShowBounds, ShowLoc, SpawnAsteroids, Suicide, ToggleAI, Traitor

Some commands are listed under both campaign and combat. These work in both contexts, but function in different ways.

[close]

Upcoming/planned features:

• More commands! If you have any requests let me know in this thread and I'll try to add them to the next version.

One final note:
While I've tried to keep everything as user-friendly as possible, this is primarily intended as a tool to aid mod development. This means it does require some knowledge of Starsector's inner workings. Most importantly, you will need to know the internal IDs of various objects in order to use any commands dealing with them. The command "list" will help with this; alternatively these IDs can be found in the data files, usually in the CSVs or variant files.

Using this mod as a cheating tool will suck all of the fun out of Starsector for you. You have been warned.

[LazyWizard]

Here's a tutorial on creating your own commands (this tutorial can also be found in the mod folder):

Spoiler

This mod supports user-created commands. A major design goal of version 2.0 was to make implementing these commands as painless as possible. This tutorial is intended to explain the new process in detail.

To add custom commands to the console you'll need a mod that contains two things: your commands' scripts, and the file data/console/commands.csv to register them in. You do not need to add Console.jar to your mod_info.json.

All commands are contained in their own separate Java class. The console mod loads command classes itself, so you can place the java files anywhere in your mod folder you want - data/console/commands is a good choice as data/console already exists to contain commands.csv. Commands can also be in jars (which shouldn't create a dependency as these classes won't be loaded if the console isn't active).

It is _highly_ recommended that you do not place your commands in data/scripts. Starsector will automatically compile any scripts in this directory or its subdirectories, and this will cause errors when the console mod is not active. Placing them elsewhere allows you to bundle commands with a regular mod that will only be loaded if the console is tagged in the launcher.

An example mod that adds several simple commands can be found in the mod folder. If you are the sort who learns best by example, you might find copying from that mod easier than following this tutorial.


 STEP 1 - THE SCRIPT
=====================

(Sometimes you may want to start with the CSV row to get a better idea of how your command will look. Just comment out the row by adding a # at the beginning to prevent the game from loading your command until it's finished)

First off, make sure your IDE has "mods/Console Commands/jars/lw_Console.jar" added as a library. Just follow the same procedure you did to add the Starsector API.

Your commands must implement the org.lazywizard.console.BaseCommand interface. This interface contains only one method (plus two enumerations, see below):
 - public CommandResult runCommand(String args, CommandContext context)

'args' is the argument(s) the player entered after this command, for example the command "addcrew 500 elite" would pass in "500 elite" as a single String. Parsing these arguments into something usable is left up to your script. This argument will never be null - if no arguments were entered, an empty String will be passed in instead.

'context' is a CommandContext passed into your script that tells it where this command was used. CommandContext is the first enum included in BaseCommand, and has the following values (these should be self-explanatory):
 - CAMPAIGN_MAP
 - COMBAT_CAMPAIGN
 - COMBAT_MISSION
 - COMBAT_SIMULATION

runCommand() returns a CommandResult, which is the other enum included in BaseCommand. CommandResult has the following possible values:
 - SUCCESS, returned when a command runs without error.
 - BAD_SYNTAX, return this if the player entered improperly formatted arguments (for example, a String where an number was expected). The console will automatically display the proper syntax to the player if this is returned.
 - WRONG_CONTEXT, if a command was entered in the wrong place (for example, using a campaign-only command during a mission).
 - ERROR, if a command used the proper syntax but still failed for some reason.

If you wish to show output to the player, Console.showMessage(String message) will format and print the String passed in to the player.

With all of this in mind, the basic structure of runCommand() is thus:
 - Check if the context passed in is a valid one for this command. Show a message and return CommandResult.WRONG_CONTEXT if the player used the command in the wrong context (ex: a camapaign travel command during combat).
 - Parse the arguments passed in. If they don't match what is expected, return CommandResult.BAD_SYNTAX (no message is needed; the console mod itself will show the proper syntax from commands.csv if BAD_SYNTAX is returned).
 - Try to run the command with the parsed arguments. If something goes wrong during this stage, show an error message and return CommandResult.ERROR. Console.showException(String message, Exception ex) can be used to display the stack trace of any exceptions to the player.
 - If everything went well, show a message and return CommandResult.SUCCESS

If you need further help implementing your command, the source files for every core command are included in jars/lw_Console.jar (most modern archive programs can open jars) in the org/lazywizard/console/commands directory. You can also find the most up-to-date source code at bitbucket.org/LazyWizard/console-commands/src


 STEP 2 - THE CSV
==================

After you have written your command's code, you will need to register it so the console can find it. Once you've done this, the mod will automatically load your command when the game starts.

Commands are registered in data/console/commands.csv. This CSV file has the following columns:
 - command: This is what the user enters to use your command.
 - class: This points to the script you wrote in Step 1 above. Use the fully-qualified name of your class (ex: data.console.commands.Example). This class can be a loose script or inside a jar, the console will work with both.
 - tags: Used with the 'help' command to find specific commands easier. For example, 'help combat' will return a list of all commands with 'combat' as one of their tags. Tags are solely a convenience feature and don't affect how your command functions in any way.
 - syntax: The basic instructions on how to use this command. Shown when a command returns CommandResult.BAD_SYNTAX, or as part of 'help <command>'
   <> - This denotes a required field
   [] - This denotes an optional field
 - help: Detailed instructions on how to use a command. Shown with 'help <command>'

Command and Class are required. Tags, Syntax and Help can be left empty, but it is HIGHLY recommended that you enter something in these fields unless this command is for personal use only.

[close]

(tutorial last updated 2015-12-11)

[xenoargh]

This is pretty amazing.

How big of a deal would it be to add some additional data display to the console?  I'd like to use this to display the information my mod needs to function a little more like how I envisioned it; it sounds like adding the relevant commands won't be a big deal, but I'd like to go even further, and use this window to display data to the end-users.  What part of this am I going need to hack to get it done?

[xenoargh]

First test run with my mod; crashed when I hit tilde, gives a null error.  I take it that I'll have to install it into the mod?  I haven't changed Corvus as the name of the System.

It also leaves a copy of itself on the buffer if you move it.

[EDIT]Installed into my mod; pretty straightforward thus far, it just works, once I got past that hurdle.  This is way, way cooler than it has any right to be, especially considering the size and relative lack of complexity. 

I'm going to have to go back to square one with how I want to display my mod's data now; I think it makes a lot more sense to build a custom variant of this to serve as the unofficial UI, if I can use it to display changing data...[/EDIT]

[CrashToDesktop]

Well...suprize, suprize, LazyWizard has come out with yet another amazing tool. I'll try it out as soon as I can get to installing it.

[Upgradecap]

Yay @ LazyWizard, for he brings glory to the modding community.





In all seriousness, this is an awesome tool that will see lots of use by us modders. (?)

[LazyWizard]

First test run with my mod; crashed when I hit tilde, gives a null error.  I take it that I'll have to install it into the mod?  I haven't changed Corvus as the name of the System.

It also leaves a copy of itself on the buffer if you move it.

Hmm,  I've tested it with several different mods, and it should just work. You should only have to tag it like a regular mod in the launcher.

It might have been something I changed to get it working without an external jar in this version. I don't suppose you would be willing to re-try and post the complete error stack trace?

How big of a deal would it be to add some additional data display to the console?  I'd like to use this to display the information my mod needs to function a little more like how I envisioned it; it sounds like adding the relevant commands won't be a big deal, but I'd like to go even further, and use this window to display data to the end-users.  What part of this am I going need to hack to get it done?

As far as I know, not possible at the moment. We don't have access to a GUI API yet, and I don't know enough OpenGL to hack together a library. The 'console' is just a JOptionPane popup right now, with a customized UIManager to fit Starfarer's theme. That's why this mod requires the game to be run in windowed mode to function (and why there would be re-paint issues while it's active - it's completely halting the main thread while the console is visible). Making your own GUI with custom JFrames isn't possible, either. Most Swing components have java.io.File in their hierarchy somewhere, so they will get blocked by Starfarer even after the upcoming changes. I've isolated the input/output in this mod so I can easily replace it if this changes later on.

However, while it's not a perfect solution, the various showMessage() methods in Console.java do make working with addMessage slightly easier. They support newlines, and word-wrap longer lines for you. Feel free to take any of the code in this mod for your own use.

[Sproginator]

A fantastic concept, shall try this tonight

[xenoargh]

If we have access to OpenGL at all, then all we really need access to is:

1.  Whatever Alex is using to display the text glyphs.  I presume that's a simple command
2.  Graphics within the starfarer directory defined within a .JSON somewhere.

We can do the rest fairly easily, if we're already allowed to capture mouse-click events and keystrokes.

[LazyWizard]

I don't know what all we have access to, actually. Out of the entire LWJGL library, I'm only using Vector2f, Display.isFullScreen(), and Keyboard.isKeyDown().

[xenoargh]

Try this out.

[EDIT]I'll try to hack a simpler version later; we really don't need GLSL to just draw a quad, lol.  But if we can draw textured quads, using named textures already available through Starfarer, and can call the text glyph system to present text at X,Y, then we can build just about anything we'd want to do... right there, in the game, like anything else in the UI.[/EDIT]

[LazyWizard]

Quick update: I made the source repository public - you can find it in the main post. The default branch won't work with Starfarer, so you will want to grab the noreflect branch.

It's a Mercurial repository because that's what I use for my solo projects. Sorry, Git/SVN users.

Try this out.

[EDIT]I'll try to hack a simpler version later; we really don't need GLSL to just draw a quad, lol.  But if we can draw textured quads, using named textures already available through Starfarer, and can call the text glyph system to present text at X,Y, then we can build just about anything we'd want to do... right there, in the game, like anything else in the UI.[/EDIT]

If we can, that would be awesome.

[Alex]

Hah, very interesting. Haven't had a chance to try it, but kudos for putting this together

it's completely halting the main thread while the console is visible.

Really? Unless you're on a Mac, it shouldn't do that. But since I don't know where you're calling JOptionPane from... ahh, I guess that would explain it. If the code displaying it ends up on the main loop somewhere (and it probably does), then I it'd hang there until it was done. So, never mind.

Try this out.

[EDIT]I'll try to hack a simpler version later; we really don't need GLSL to just draw a quad, lol.  But if we can draw textured quads, using named textures already available through Starfarer, and can call the text glyph system to present text at X,Y, then we can build just about anything we'd want to do... right there, in the game, like anything else in the UI.[/EDIT]

Don't bother with shaders. Starfarer uses the fixed function pipeline, and the two are incompatible. Shaders are an all-or-nothing way of doing it - you can't only use them for some things.

If you're not familiar with OpenGL, I'd suggest being very careful. It's pretty easy to crash the graphics driver by doing some ill-advised OpenGL calls - which can mean a system hang / hard reboot.

Although, that's kind of a moot point. Since there are currently no callback from within the rendering portion of the loop, anything you try to draw would get cleared out before the start of the next frame's rendering - you'd never see it.

We can do the rest fairly easily, if we're already allowed to capture mouse-click events and keystrokes.

There's some potential for unintended interactions here, too (using Keyboard.poll() or Mouse.poll() would break the game).

[LazyWizard]

Hah, very interesting. Haven't had a chance to try it, but kudos for putting this together

I don't suppose you would be willing to try the main branch and see if it runs in the latest development version? I've been using a lot of guesswork, but I'm almost certain it will work without tweaking given the changes you mentioned in our conversation.

it's completely halting the main thread while the console is visible.

Really? Unless you're on a Mac, it shouldn't do that. But since I don't know where you're calling JOptionPane from... ahh, I guess that would explain it. If the code displaying it ends up on the main loop somewhere (and it probably does), then I it'd hang there until it was done. So, never mind.

I intentionally called it that way, as it makes things much simpler for me. I did try making a multi-threaded version of this mod instead of using a SpawnPointPlugin, but there were so many edge cases (foremost being making sure the player is actually on the campaign map when the command is finally entered) that it just wasn't worth fixing all the potential pitfalls. The console implementation is isolated so I can replace it later if I change my mind.

[xenoargh]

If it's just using fixed-function pipeline, that's fine; all we really need to do is draw some textured quads and make calls to display strings via your glyph system, nothing terribly fancy.

Anyhow,

Code

import org.lwjgl.opengl.GL11;
import org.lwjgl.util.glu.GLU;

That's already compiling, so we're fairly close.  It's too bad we don't have a callback atm, I think that simple test stuff's already possible.

There's some potential for unintended interactions here, too (using Keyboard.poll() or Mouse.poll() would break the game).

Yeah, we'd need to know how to safely do that.

Pretty stoked, though; instead of pestering you about building some UI stuff, we could just do it, I think.