Lib Starmap

Overview

Still from the dynamic display of Starmap on a "mission screen"

Still from the display placed on the View Screen while in flight
This is controlled by use of the ASC

Lib_Starmap introduces In-System-Maps in 3D (or 2.5D *sigh*). These maps can be shown on missionScreens and inflight. On missionScreens they can be animated (e.g. through Lib_Animator). Inflight users can control them via the Advanced Space Compass. Usage for AddOns is easy.

Lib_Starmap requires shader support to work.

Technical

missionScreen

Lib_Starmap creates a missionScreen and places the objects based on real world coordinates and assigns textures. Up to 12 elements can be shown (either standard objects like the sun, planet, mainStation, etc or custom). The object positions are scaled down for display. Far out positions beyond a hardcoded point are compressed, so it will still work even if AddOns like DistantSuns are used. The next step is to zoom the whole thing to fit in the screen. And finally it can be animated (optional) to give a visual impression of the things the player should know. Animations can contain text, sounds and movements. The created objects are just planes using a billboard vertex shader, so they will always point to the player. Standard objects like secondary stations, carriers, beacons will use a color-scheme, custom objects can use this scheme as well.

Inflight

The mechanism allows inflight usage as well. This is specially interesting for missions. The script creates a visualEffect for it and tracks marked objects to update positions on the map. If they slip away (exploded, removed or jumped) they are cleaned from the map. The map disables itself on red alert and enables itself again when things have settled. The orientation of the map is bound to the compass, so you can control it easily to see it from different angles. The visualEffect gets removed on docking, dying or jumping.

General

Both maps (missionScreen and inflight) do work in interstellarSpace as well, so it is possible to get back to the [0,0,0] position, which was hard before (through using the FPS display). The maps are not accessible through equipment or interface handling - they have to be called by script. And the calling script decides what kind of elements will be shown. Usage for scripts is easy - for a standard setup it's only one line of code!

Alternative Wording

There is an alternative description by Svengali here in a 2018 post on the Library BB thread.

Methods

_start

	_start: function( obj, force )

Start a map on .missionScreenOpportunity or .shipLaunchedFromStation.

One of 22 starmap sprites

Parameters:

obj

Object.

ini

Array. Required. Max 12 entries. Either String or Object { map:TEXTURE, ent:ENTITY [,col:Number] }

PS

Player ship.

WP

Witchpoint.

S

Sun.

P

Planets (the first one will be the mainPlanet).

M

Moons.

ST

Main station.

STG

Secondary stations with allegiance of galcop, hunter or neutral.

H

Rock Hermit.

AS

Asteroid fields.

message

String. Optional. Initial message text.

title

String. Optional. Screen title.

ani

Object. Optional. Animation for Lib_Animator. Requires capture flag!

force

Bool. Optional. Forces update of system entities before settings up the map.

Returns:

true or false.

Example:

worldScripts.Lib_Starmap._start({ini:["PS","WP","P","S","ST","H","AS","AS","AS","AS","AS","AS"]});

Example

This is the script.js file taken from the Starmap-Demo.oxz (the only other content is a manifest.plist)

/* global player,system,worldScripts */
/* (C) Svengali 2016-2018, License CC-by-nc-sa-4.0 */
(function(){
"use strict";
this.name = "Lib_Starmap_Demo";

// ini is required, ani is ignored inflight.
this.$map = [
	{ini:["PS","WP","P","S","ST","H","AS","AS","AS"],ani:{capture:1,model:"lib_ms_helper12",flow:[]},title:"EX: Standard"},
	{ini:["P","ST",
		{map:"lib_starmap_i2.png",pos:player.ship.position.add([3000,30000,-100000]),col:1},
		{map:"lib_starmap_i3.png",pos:player.ship.position.add([-13000,-3000,-200000]),col:1},
		{map:"lib_starmap_i4.png",pos:player.ship.position.add([-30000,-70000,-260000]),col:1},
		{map:"lib_starmap_i4.png",pos:player.ship.position.add([-30000,-70000,660000]),col:4}],
		ani:{capture:1,model:"lib_ms_helper12",flow:[]},
		POI:player.ship.position,MUL:0.0002,title:"EX: Briefings"}
];
this.$flow = [
	// Example 1
	[[0,"rotw",{e:-1,t:90,rx:0.0009,ry:0.0009}],
	[1,"aiFace",{e:0,dest:3}],[2,"txt","1. You are here."],[3,"prop",{e:4,p:"lightsActive",v:true}],
	[19,"prop",{e:4,p:"lightsActive",v:false}],[20,"txt","2. Fly to the sun."],[21,"prop",{e:3,p:"lightsActive",v:true}],[23,"aiFly",{e:0,spd:160,rng:10,dest:3}],
	[47,"txt","3. Gather the data."],[48,"aiFace",{e:0,dest:4}],
	[60,"prop",{e:3,p:"lightsActive",v:false}],[61,"txt","4. Return to us."],[62,"prop",{e:4,p:"lightsActive",v:true}],[63,"aiFly",{e:0,spd:30,rng:10,dest:4}],
	[98,"txt","5. Continue for another example."],[99,"reset"]],
	// Example 2
	[[2,"txt","1. Several enemy ships are approaching."],[3,"prop",{e:2,p:"lightsActive",v:true}],[4,"prop",{e:3,p:"lightsActive",v:true}],[5,"prop",{e:4,p:"lightsActive",v:true}],
	[20,"prop",{e:2,p:"lightsActive",v:false}],[21,"prop",{e:3,p:"lightsActive",v:false}],[22,"prop",{e:4,p:"lightsActive",v:false}],
	[23,"txt","2. We have called the HMS Spear for support."],[25,"prop",{e:5,p:"lightsActive",v:true}],
	[43,"prop",{e:5,p:"lightsActive",v:false}],[44,"txt","3. Protect the station until it arrives."],
	[45,"prop",{e:1,p:"lightsActive",v:true}],
	[65,"txt","Now try it inflight .-)"],[66,"reset"]]
];
this.$MSShown = 0;
this.$FLShown = null;
this.$c = 0;

this.missionScreenOpportunity = function(){
	if(this.$MSShown>1 || system.isInterstellarSpace) return;
	var map = this.$map[this.$MSShown];
	map.ani.flow = this.$flow[this.$MSShown];
	worldScripts.Lib_Starmap._start(map);
	this.$MSShown++;
};
this.shipLaunchedFromStation = function(){
	if(this.$FLShown || system.isInterstellarSpace) return;
	this.$FLShown = 1;
	worldScripts.Lib_Starmap._start({ini:["PS","WP","P","S","ST","H","AS","AS","AS"]});
	this.$InstructionTimer = new Timer(this,this._giveInstructions,0,10);
	this.$CMP = player.ship.equipmentStatus("EQ_ADVANCED_COMPASS");
};
this._giveInstructions = function(){
	if(!player.ship || !player.ship.isInSpace || player.ship.docked || this.$c>6){
		this.$InstructionTimer.stop();
		delete this.$InstructionTimer;
		return;
	}
	if((this.$c!==3 && player.alertCondition===3) || (this.$c && player.ship.weaponsOnline)){
		player.consoleMessage("Waiting...",8);
		return;
	}
	switch(this.$c){
		case 0:
			if(player.ship.weaponsOnline) player.consoleMessage("Disable your weapons to enable the map.",8);
			else player.consoleMessage("The map shows up only with disabled weapons.",8);
			break;
		case 1:
			player.consoleMessage("Control the map via your Compass.",8);
			if(this.$CMP!=="EQUIPMENT_OK"){
				if(player.ship.canAwardEquipment("EQ_ADVANCED_COMPASS")){
					player.ship.awardEquipment("EQ_ADVANCED_COMPASS");
					player.consoleMessage("We gave you one to try it out.",8);
				}
			}
			break;
		case 2:
			player.consoleMessage("On red alert it disables itself.",8);
			this.$T = system.addShips("thargoid",1,player.ship.position.add([10000,0,0]),2560)[0];
			if(this.$CMP==="EQUIPMENT_UNAVAILABLE") player.ship.removeEquipment("EQ_ADVANCED_COMPASS");
			break;
		case 3:
			player.consoleMessage("And reenables itself after it, if your weapons are off.",8);
			if(this.$T && this.$T.isValid) this.$T.explode();
			break;
		case 4: player.consoleMessage("Funny thing, isn't it?",8); break;
		case 5: player.consoleMessage("On docking/jumping/dying it removes itself.",8); break;
		case 6:
			var x1 = system.addShips("strut",1,system.mainStation.position.add([200000,-200000,-100000]))[0];
			if(x1){
				x1.displayName = "Test target";
				x1.script.shipDied = function(whom){if(whom && whom.isPlayer) player.consoleMessage("Congratulations! You've squashed it. Demo is over now.",8);};
				if(worldScripts.Lib_Starmap._addInFreeSlot(x1,"lib_starmap_i8.png",6)){
					player.consoleMessage("As last step some practice.",8);
					player.consoleMessage("Locate the added target and destroy it.",8);
				} else player.consoleMessage("That's it.",8);
			} else player.consoleMessage("That's it.",8);
			break;
	}
	this.$c++;
};
}).call(this);

Downloads

• Starmap Demo (oxz, 2.4 KB)
• Animator Demo (zip, 2.8 MiB): a helper for animations on mission screens

Links

• Library OXP
• Cabal Common Library OXP, Lib.oxp's precursor, also featured a Cutscene addon - it was broken by one of the Vanilla game updates.