[X3 + TC] Guida al Plugin Manager

[BlackRazor]

Attenzione: il vecchio Plugin Manager (oggetto di questa guida) non è più supportato dal suo autore e non è più scaricabile.
Cycrow ha creato un nuovo Plugin Manager che sostituisce quello vecchio; il topic di riferimento è questo.
Questa guida non è valida per il nuovo Plugin Manager e viene lasciata qui solo per motivi storici e per chi ancora usa la vecchia versione.




Guida all’uso del Plugin Manager

Era ormai da un po’ di tempo (da più di un anno per la verità ) che volevo scrivere una guida sull’uso del Plugin Manager di Cycrow, un software che è si è imposto come lo standard per l’installazione e la gestione di script non firmati su X3 e TC. Molte persone (me compreso) all’inizio lo hanno snobbato per il semplice motivo che non volevano installare (e imparare a usare) un software per installare gli script visto che era possibile ottenere lo stesso risultato semplicemente copiando dei file in cartelle di X3 o TC; dopo averlo usato posso tranquillamente dire che non ne farei assolutamente a meno e anzi aggiungo che tutti gli script che sfortunatamente non usano questo programma vengono da me immediatamente convertiti perché non ho più alcuna intenzione di installare manualmente gli script. Questa guida si compone di due parti: la prima mostrerà come installare script in formato spk (Script Packager), la seconda mostrerà come creare file spk a partire da file “sfusi”. Prima però è necessaria una piccola introduzione.


Nota Bene

Questa guida si riferisce a X3:Terran Conflict e all’ultima versione disponibile del Plugin Manager al momento della stesura della guida (2.20 beta 6). Cycrow può in qualunque momento aggiungere/togliere/modificare parti del suo programma per cui tenete conto che non tutte le informazioni contenute in questa guida saranno valide per sempre; si noti inoltre che questa guida non spiega come installare o creare navi attraverso il Plugin Manager e non penso di aggiungere una parte contenente queste informazioni in futuro. Questa guida non è pensata per spiegare ogni singola opzione o procedura del Plugin Manager bensì per permettere di imparare ad eseguire le operazioni più importanti e utili in breve tempo; se si hanno dei dubbi su alcune funzionalità non spiegate in questa guida si invita a leggere la documentazione del programma (accessibile dal menu “Help” del programma stesso).
Infine faccio notare che quasi tutte le informazioni qui esposte sono valide anche per X3:Reunion e per le versioni precedenti del Plugin Manager (che supportano solo i “vecchi” X2 e X3:Reunion).


Perché dovrei usare il Plugin Manager ?

Prima di spiegare come usare questo strumento ritengo sia doveroso spiegare perché andrebbe usato; i motivi sono molteplici e riguardano sia gli script che i mod.

1. Script: in questo caso il Plugin manager va usato per i seguenti motivi:
   • Quasi tutti gli script necessitano di questo strumento per essere installati
   • Tutti i file vengono automaticamente installati nella cartella corretta, niente più errori di installazione
   • I file di testo vengono automaticamente modificati in modo da essere compatibili con la lingua in cui avete installato il gioco, niente più modifiche manuali al nome e al contenuto dei file di testo (con conseguenti errori ReadText in caso di modifica sbagliata)
   • La disinstallazione degli script diventa semplicissima: basta un solo click e il gioco è fatto, niente più cancellazione manuale di file che comportava problemi quali file inutili che rimangono nella cartella del gioco e file importanti cancellati per errore con conseguenti problemi di stabilità del gioco. Inoltre alcuni script per poter essere disinstallati devono prima essere “disattivati” facendo girare un apposito script di disinstallazione e poi possono essere cancellati; anche questa procedura è presente e automatizzata nel Plugin Manager.
   • In alcuni casi i file spk contenenti script o mod possono essere aggiornati automaticamente quando esce una nuova versione dello script/mod in questione
   • E’ possibile disattivare temporaneamente uno script senza disinstallarlo
   • Permette di usare le Custom Wares che semplificano di molto la vita a chi crea script che fanno uso di merci personalizzate (ad esempio nuovi software per le navi)
   • Permette di vedere se ci sono conflitti tra script
2. Mod: il Plugin Manager può essere usato per installare mod (sia mod normali che false patch); questo è importante per i seguenti motivi:
   • Se si installano mod sotto forma di falsa patch e poi si patcha il gioco alcuni dei mod verranno cancellati; con il Plugin Manager un’apposita opzione permette di patchare il gioco senza perdere alcun mod
   • Le false patch altro non sono che mod i cui file hanno come nome un numero; se si hanno varie false patch installate diventa difficile associare ogni numero al relativo mod; con il plugin manager ogni falsa patch è associata al nome del mod relativo quindi questo problema scompare
   • Installando un mod sotto forma di falsa patch con il Plugin Manager ci penserà il programma stesso a mettere il file nella cartella corretta e soprattutto ad assegnargli il nome corretto
   • E’ possibile creare i cosiddetti profili: ogni profilo ha associato un mod e una cartella contenente dei salvataggi; in questo modo è possibile usare più mod con una sola installazione e ogni mod ha dei salvataggi separati. Questo è importante perché in generale i mod non sono compatibili gli uni con gli altri

[BlackRazor]

Parte 1: Come installare pacchetti in formato spk


Fase 1: Installazione e configurazione del Plugin Manager

Per prima cosa sarà ovviamente necessario scaricare, installare e configurare il Plugin Manager. Il topic di riferimento per questo software è questo; qui troverete sempre l’ultima versione del Plugin Manager oltre a una discussione su bug presenti, futuri miglioramenti, ecc.
Dopo aver scaricato il Plugin Manager è necessario installarlo, lo può installare in qualunque cartella; personalmente io ho installato Terran Conflict in C:\Giochi\X3 Terran Conflict e il Plugin Manager in C:\Giochi\X3 Terran Conflict\X Plugin Manager. Durante l’installazione è possibile spuntare l’opzione “Register file extensions” che se attiva fa in modo che basti fare doppio click su un file spk per installarlo con lo script manager.
Al primo avvio del programma verrà mostrata una procedura guidata che permetterà di configurare gli aspetti essenziali del programma; è possibile saltare questa procedura ed eventualmente eseguirla in seguito ma lo sconsiglio altamente: meglio spendere un paio di minuti per configurare tutto subito.
La prima schermata vi chiederà di impostare la lingua del Plugin Manager; attualmente sono disponibili solo inglese, russo e spagnolo per cui suggerisco la prima opzione (tutta la guida farà riferimento alla versione inglese).
La schermata successiva mostrerà tutte le installazioni di giochi compatibili che sono state trovate dal Plugin Manager; è possibile spuntare “Search for more X-Universe Installations” se la propria installazione non compare nella lista.
La terza schermata è molto importante perché indica per quale lingua verranno preparati i file di testo usati dagli script; se si seleziona la lingua sbagliata tutti i testi degli script installati verranno sostituiti dai famigerati errori ReadText rendendo gli script inutilizzabili. La lingua selezionata in questa schermata deve essere la stessa della propria installazione di Terran Conflict; ad esempio se si è installato Terran Conflict in italiano la lingua selezionata in questa schermata deve essere la lingua italiana altrimenti il gioco si rifiuterà di caricare i testi degli script. Se si lascia l’impostazione di default (“Automatic Language Setting”) il Plugin Manager legge automaticamente la lingua di installazione di Terran Conflict e fa gli aggiustamenti del caso; se invece volete selezionare manualmente la lingua dovete cliccare su “Manual Language Setting”, poi su Custom e infine inserire manualmente l’identificativo della lingua che coincide con il prefisso telefonico internazionale del Paese la cui lingua volete usare (ad esempio 39 per l’italiano). Il mio consiglio è di lasciare l’impostazione di default (selezione automatica della lingua); sconsiglio invece vivamente di selezionare l’opzione “Don’t Bother” perché in quel caso il Plugin manager non farebbe alcun adattamento automatico dei file di testo.
Ora apparirà la schermata principale del Plugin Manager e potrete configurare ulteriormente il Plugin Manager; per fare ciò cliccate su “Settings -> Configure Installer”.
Sotto “Main Settings” controllate che “Allow use of Custom Wares” sia selezionato.
Sotto “Modules” nell’area “Mod Profiles” è possibile selezionare “Enable” se si vuole far uso dei profili (cfr. sezione “Mod” di “Perché dovrei usare il Plugin Manager ?”).


Fase 2: Installazione di script e mod

A questo punto siete pronti ad installare script e mod purché tali aggiunte siano già in formato spk. Tutto ciò che dovete fare è cliccare su “File -> Install Script” e selezionare il file spk da installare; nonostante il nome sia fuorviante questo comando può essere usato per installare script e mod in formato spk e anche navi in formato xsp. Una volta installato uno script (o un mod) è possibile eseguire alcune operazioni:

• Cliccando sullo script appare in basso una piccola area di testo contenente alcune informazioni base sullo script.
• Cliccando con il tasto destro del mouse su uno script appare un menu contestuale che permette di:
  1. Rimuovere lo script (comando “Remove Package”)
  2. Disabilitare temporaneamente lo script senza disinstallarlo (comando “Disable”); una volta disabilitato basta selezionare il comando “Enable” per ri-abilitarlo
  3. Leggere il file Readme dello script (comando “View Readme”). E’ assolutamente essenziale leggere il Readme di uno script per sapere che cosa fa lo script e come va usato

Fase 3: Altri comandi importanti

Come già accennato alcuni script hanno bisogno che venga eseguito uno script di disinstallazione prima di poter venire completamente rimossi (ciò verrà specificato nel file Readme dello script, motivo in più per consultare tale file). Se la procedura è necessaria basta cliccare con il tasto destro del mouse sullo script e selezionare “Remove Package”; successivamente avviare Terran Conflict, caricare la partita, attendere che lo script di disinstallazione termini il proprio compito, salvare e uscire dal gioco; ora basta aprire il Plugin Manager e cliccare su “Advanced -> Clear Uninstall Scripts” per eliminare gli script di disinstallazione orami inutili.

Nel caso in cui abbiate installato mod sotto forma di falsa patch con il Plugin Manager dovrete seguire una procedura particolare per patchare il gioco: aprite il Plugin Manager e selezionate “Advanced -> Prepare to Patch Game”; ora chiudete il Plugin Manager, patchate il gioco e infine riaprite il Plugin Manager e selezionate “Advanced -> Finished Patching Game”.

Per controllare se è disponibile un aggiornamento del Plugin Manager basta cliccare su “Update -> Check for Updates”.

Per controllare se ci sono aggiornamenti per gli script (o mod) installati cliccare su “Update -> Package Updates” ma tenete conto che tale opzione funziona solo se il file spk è stato configurato correttamente e l’autore dello script ha accesso a un server ftp su cui uploadare gli script; siccome queste condizioni raramente si verificano si consiglia di controllare periodicamente sul forum per sapere se ci sono aggiornamenti per gli script installati.


Addendum

Gli script non ufficiali hanno bisogno che lo script editor sia attivo per poter funzionare; in alcuni casi ciò viene effettuato automaticamente dallo script stesso, in altri bisognerà agire manualmente. Ad ogni modo consiglio sempre di attivare lo script editor manualmente; le istruzioni per fare ciò si trovano qui. Dopo aver attivato lo script editor è necessario salvare, uscire e ricaricare la partita affinché gli script non ufficiali possano funzionare.
Si noti che dopo aver attivato lo script editor una volta che si salva la partita questa informazione viene scritta nel salvataggio quindi non c'è bisogno di attivare lo script editor ogni volta che si installa un nuovo script; però se si comincia una nuova partita o se carica un salvataggio precedente all'attivazione dello script editor bisognerà ripetere questa procedura.
Infine tengo a far notare a tutti che l’installazione di script/mod non ufficiali renderà la vostra partita “modificata”; tale informazione verrà scritta nel salvataggio e vi rimarrà permanentemente rendendo impossibile l’uso della funzione Uplink sul sito della Egosoft; tutti i problemi generati da script/mod non ufficiali non sono da imputare alla Egosoft e non danno diritto all’utilizzo del forum di Supporto Tecnico o a qualunque altra richiesta di supporto ufficiale.


Con questo si conclude la prima parte della guida al Plugin Manager, nella prossima parte verrà spiegato come utilizzare lo Script Packager per creare pacchetti spk.

[BlackRazor]

Parte 2: Come creare pacchetti spk

Creare un pacchetto spk è molto più semplice di quanto si possa pensare ed è utile nel caso in cui si abbia in mano uno script o un mod (soprattutto una falsa patch) che non sia già in formato spk (cfr. primo post, sezione “Perché dovrei usare il Plugin Manager ?”).


Fase 1: I tipi di file

Per prima cosa è necessario capire con che tipo di file avremo a che fare.
Per quanto riguarda gli script i file che dovremo “impacchettare” sono principalmente di due tipi: file di script e file di testo.

• I file di script sono file xml che contengono “la logica“ dello script, cioè il codice dello script
• I file di testo sono anche loro file xml che contengono il testo che verrà mostrato a schermo; questi file vengono caricati e usati dai file di script per mostrare informazioni e permettere l’interazione con gli utenti. Sono questi i file che vanno tradotti quando si vuole tradurre uno script ed esistono proprio per questo motivo: per separare la logica dello script dal testo e per permettere di tradurre uno script senza toccare il codice (il che permette anche a chi non ha alcuna nozione di programmazione o di scripting di tradurre lavori altrui)

Altri file che possono essere utili quando si parla di scripting sono gli script di disinstallazione (cfr. introduzione e prima parte della guida): questi sono, in pratica, normali file di script ma il Plugin Manager li tratta come file separati in modo da poterli distinguere al volo dai normali file di script e da poterli eseguire non appena lo script relativo viene disinstallato.
Per quanto riguarda i mod gli unici file che li compongono sono i file cat e i file dat; questi file viaggiano sempre “in coppia” cioè un mod è descritto da una coppia di file con lo stesso nome, uno dei due file ha estensione cat e l’altro ha estensione dat.
Infine essenziali sono i file Readme, file di testo (formato txt) che possono venire visualizzati direttamente dall’interno del programma e che contengono informazioni sull’uso dello script (o del mod) contenuto nel pacchetto.


Fase 2: Creazione del pacchetto

A questo punto si passa alla creazione del pacchetto stesso.

• Per prima cosa è necessario aprire lo Script Packager e inserire le informazioni essenziali riguardanti il pacchetto stesso; tali informazioni verranno inserite nella linguetta “Script Settings”. In generale è buona norma inserire più informazioni possibili, perlomeno nome dello script, autore e versione; inserendo queste informazioni sarà semplice individuare lo script nella lista di script installati e sapere al volo se è necessario aggiornarlo oppure se è già all’ultima versione disponibile. E’ possibile inserire anche il tipo di pacchetto che stiamo creando e una breve descrizione che apparirà ogni volta che ci cliccheremo sopra.
• Nelle altre linguette troveremo varie altre opzioni attivabili e informazioni da inserire per personalizzare meglio il nostro pacchetto. L’unica informazione che ritengo veramente importante è la selezione del gioco/patch necessario per usare questo pacchetto; tale informazione può essere inserita usando il menu a tendina “Game Version” della linguetta “Advanced”. Ricordo a tutti che, tranne casi particolari, script e mod non sono compatibili tra un prodotto e l’altro per cui si consiglia di inserire sempre questa informazione in modo da sapere sempre quali pacchetti possiamo usare e quali invece sono per altri giochi.
• Prima di aggiungere file è necessario spiegare a cosa serve la parte inferiore della finestra: in quello spazio vengono listati tutti i file che sono stati aggiunti al pacchetto e il relativo tipo; all’avvio del programma ovviamente tale finestra è vuota. E’ possibile usare il menu a tendina “Display File Filter” per filtrare quali file verranno mostrati nell’area “Package Files”.
• A questo punto possiamo cliccare su “Add File(s)” per aggiungere file al nostro pacchetto; se il filtro “Display File Filter” è impostato su “All Files” allora ci verrà chiesto quale tipo di file vogliamo inserire, altrimenti il programma ci permetterà di aggiungere solo file dello stesso tipo che stiamo filtrando (ad esempio se il filtro è impostato su “Text Files” potremo aggiungere solo file di testo). Se si vuole rimuovere un file basta selezionarlo nell’area “Package Files” e poi cliccare su “Delete Selected”; se si vogliono eliminare tutti i file del pacchetto basta cliccare su “Clear All”.
• Nota importante sui mod: se il nome dei due file che compongono il mod non è un numero allora i file verranno messi nella cartella “mods” del gioco; a questo punto il mod dovrà essere attivato nel launcher del gioco. Se invece il nome è un numero (ad esempio 01.cat e 01.dat) allora il mod verrà considerato una falsa patch: all’atto dell’installazione i nomi dei file verranno automaticamente modificati in modo da diventare delle false patch e se si richiede la disinstallazione del mod tutte le false patch successive verranno rinominate in modo da continuare ad essere riconosciute e utilizzate dal gioco; per questo motivo se state inserendo un mod sotto forma di falsa patch nel pacchetto consiglio sempre di rinominare i file che lo compongono in 01.cat e 01.dat. Si noti infine che in un pacchetto ci possono essere più mod e più false patch.
• A questo punto basta cliccare su “Save As” per salvare il pacchetto. I pacchetti spk sono compressi tramite 7zip il che permette di ottenere file piccoli ma richiede parecchio tempo per la creazione del pacchetto stesso; se il pacchetto contiene mod grossi (nell’ordine delle decine di mega) è possibile che ci vogliano parecchi minuti per la sua creazione.
• Il pacchetto è ora pronto per essere installato o distribuito su Internet; ricordate sempre che se lo script o il mod non è vostro dovete avere il permesso esplicito dell’autore prima di poterlo ridistribuire (vale anche se non avete modificato lo script o il mod e vi siete limitate a creare un pacchetto spk a partire da semplici “file sfusi”).

Questa è la procedura nel caso abbiate “file sfusi” e vogliate creare pacchetti spk; volendo, però, potete anche modificare pacchetti spk già esistenti (ad esempio nel caso in cui sia uscita una nuova versione dello script). Per fare ciò basta avviare lo Script Packager, cliccare su “File -> Open Package” e selezionare il pacchetto da aprire; a questo punto potete procedere come spiegato sopra per modificare il pacchetto. Al termine delle modifiche potete cliccare su “Save As” se volete salvare il pacchetto su un nuovo file oppure “Save” se volete sovrascrivere la vecchia versione del pacchetto con quella nuova.

[BlackRazor]

Come potete vedere la prima parte della guida è disponibile mentre per la seconda parte bisognerà attendere ancora un po’. Se avete commenti/dubbi/aggiunte/consigli postate pure qua sotto, anche se si tratta solo di riportare un errore grammaticale che ho commesso nella stesura della guida. Spero che la guida possa essere utile, soprattutto a chi per la prima volta decide di usare script/mod o a chi non mastica bene l’inglese.

Ciao.

[krimax]

Suggerimenti da darti non ne ho.Volevo solo ringraziarti per l'ottimo lavoro che stai facendo per la comunità italiana.Gran bel lavoro

[dony93]

Bel lavoro BlackRazor,si rivelerà sicuramnte molto utile per "i nuovi modders" .

[DannyDSC]

Grande Black , come al solito oltre che aiutare tutti e moderare il forum, crei delle guide ben fatte e precise .

Bravo!

[BlackRazor]

Aggiunta la seconda e ultima parte della guida, come detto sopra invito chiunque a postare qui sotto suggerimenti, correzioni ortografiche, richieste, consigli, etc. Per chi non lo avesse notato la guida è anche stickata qui.