Tú eliges Capital SimCity Capital Sims Capital Spore
Capital SimCity

[Tutorial] CiSk - C# Modding: 001 - Primeros pasos

Subforo dedicado para publicar los mods más destacados creados por la comunidad.

Moderador: Equipo moderador [CSC]

[Tutorial] CiSk - C# Modding: 001 - Primeros pasos

Notapor wyllman » 21 Jul 2015, 23:23

1. Primeros Pasos.

Cities Skylines está creado usando la plataforma Unity 5 aprovechando el gran potencial de scripting que nos ofrece. Además de los recursos que ofrece el juego para la comunidad de programadores, se tiene también acceso a las funcionalidades de las librerías de Unity. Esto, inicialmente nos abre un gran abanico de posibilidades para la modificación del juego.

En este tutorial iremos explorando los primeros pasos a tener en cuenta para la realización de tu propia modificación del juego. Todo el trabajo se ha realizado bajo un sistema windows, en algunos casos puede encontrarse diferencias con otros sistemas, pero en su mayoría debería funcionar tanto para mac como para linux.

Cabe destacar también que todos los códigos se van a probar con la versión 1.1.1b del juego.

1.1. C# y Cities Skylines, conceptos básicos.

Las modificaciones para el juego, se implementan usando el lenguaje de programación C#. Es el lenguaje base para el sistema de scripts, tanto de Unity como del juego. El conjunto de clases o archivos “.cs” que van a componer nuestra modificación, han de compilarse en una librería “.dll”.

Una vez tengamos nuestra librería compilada y lista para usar, nos dirigimos a la carpeta “...\Cities_Skylines\Addons\Mods\” (también puede encontrarse en “...\Cities_Skylines\Files\Mods\”). En este lugar, se crea una carpeta con el nombre de nuestra modificación y en ella se copia el archivo “.dll”. Con esto tenemos lista nuestra modificación para que el juego la utilice.

Por defecto el juego desactiva toda modificación nueva que se encuentre y es trabajo nuestro ir al gestor de contenidos(Pantalla principal del juego), en el apartado “mods” y activarla manualmente.

1.2. Herramientas básicas.

Para el desarrollo de este tutorial se va a implementar todas las modificaciones utilizando la plataforma gratuita Visual Studio Community 2013. Con ella se desarrollará el código y se compilarán nuestras librerías (.dll).

Teniendo en cuenta que la documentación existente hasta la fecha no es muy extensa, sobre todo en la parte que concierne al uso de las librerías propias del juego. Vamos a conseguir una herramienta que descodifique librerías “.dll” y nos muestre su contenido. La herramienta que se va a usar será ILSpy. Una vez ejecutado el programa, tan solo has de arrastrar el archivo “.dll” del juego que quieras observar a la ventana y ala a investigar. Este proceso no da un código tan legible como el código fuente creado por el programador, ten en cuenta que ha pasado por un compilador que le habrá hecho ciertas modificaciones (además de eliminar los comentarios en el código), pero con paciencia resulta bastante útil. Podrás también observar las modificaciones de otros y así aprender más rápidamente con ejemplos reales de cambios en el juego.

1.3. Inicializando un proyecto en Visual Studio.

Lo primero que vamos a hacer es crear un nuevo proyecto (File > New > Project). En el asistente para la creación de proyectos buscamos la plantilla para librerías en c# (Class Library) y le damos un nombre a nuestro proyecto. Selecciona la carpeta donde se guardaran los archivos fuente del proyecto (ojo, usa una carpeta externa al conjunto de carpetas donde está instalado el juego) y pulsa OK.

El siguiente paso es añadir a la configuración del proyecto las referencias a las librerías que se van a usar en nuestra modificación. Nos dirigimos al asistente de referencias de Visual Studio (Project>Add Reference) clickeamos en el botón “browse” y en de la carpeta “...\Cities_Skylines\Cities_Data\Managed\” buscamos los archivos que queramos enlazar. El archivo ICities.dll es la librería que ofrece el juego a la comunidad de desarrolladores para facilitarles la tarea, pero además es conveniente no perder de vista Assembly-CSharp.dll y ColossalManaged.dll que son las librerías de las principales funcionalidades del juego (sin documentación pública o accesible) y por último nos encontramos con UnityEngine.dll y UnityEngine.UI.dll las librerías del motor de juegos Unity.

Cabe destacar que al crear nuestro proyecto, Visual Studio lo configure para usar “.Net Framework 4.5”. Esto no debería dar problemas para muchas de las funcionalidades que programemos, pero como veremos en el siguiente capítulo, si usamos, por ejemplo, “System.Action” y lo compilamos usando el framework 4.5, al ejecutar la modificación en el juego, este nos dará un error diciendo que no encuentra “System.Action”. La solución que he encontrado a este problema es cambiar la configuración de nuestro proyecto a “.Net Framework 3.5”. Para ello, una vez creado nuestro proyecto, nos dirigimos a (Project> NameProject Properties…), dentro en la sección “Application” y en “Target framework:” seleccionamos “.Net Framework 3.5”.Y compilamos.


Para compilar nuestro proyecto tan solo tendremos que pulsar F6 o ir a (Build>Build Solution), esto creará nuestro archivo “nombre_proyecto.dll” en la carpeta “...\nombre_proyecto\obj\Debug” o “...\nombre_proyecto\obj\Release” según tengas configurado el proyecto en Visual Studio. Copiamos nuestro archivo a la carpeta de mods del juego y lo activamos en el gestor de contenidos para probar nuestra modificación.

Ojo, cada mod o librería ha de tener su propia carpeta dentro de la carpeta de mods del juego.

1.4 Empezando a programar.

Ya hemos creado nuestro nuevo proyecto con el asistente y enlazado las librerías que vamos a usar. Deberíamos tener un código parecido al siguiente:


Código: Seleccionar todo
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace NombreProyecto {
    public class Class1 {

    }
}


Las primeras 5 líneas “using …” nos dan acceso a los espacios de nombres de las distintas librerías de C#, Unity, CitiesSkylines, otras… es conveniente dejar la primera línea(de estas 5), el resto de momento las podemos eliminar. Por norma general añadiremos:

Código: Seleccionar todo
using ICities;
using UnityEngine;


La sexta línea crea un nuevo espacio de nombres para nuestra modificación, cada vez que accedas a un atributo, clase o función de dicho espacio de nombres tendrás que escribir “NombreProyecto.funcion1 ();” por ejemplo.

Dentro del cuerpo del espacio de nombres creado tenemos la estructura básica de una clase:

Código: Seleccionar todo
public class Class1 {
}


“Class1” representa el nombre de la clase, que deberemos cambiar a algo más significativo. La primera clase que vamos a crear va a tener como objetivo hacerle ver al juego que nuestra librería es una modificación apta para el mismo.

Modificamos la clase Class1, buscándole un nombre más adecuado, por ejemplo NombreProyectoInfo y le diremos que herede el comportamiento del módulo IUserMod de la librería ICities, es decir:

Código: Seleccionar todo
public class NombreProyectoInfo : IUserMod {
}


A continuación, dentro del cuerpo de esta clase, añadiremos el acceso a los atributos de nombre y descripción de nuestra modificación, es decir:

Código: Seleccionar todo
public class NombreProyectoInfo : IUserMod {
   public string Name {
      get { return "El nombre de mi modificación"; }
   }

   public string Description {
      get { return "La descripción de mi modificación "; }
   }
}


Con esto, el juego ya es capaz de detectar tu librería y mostrarla en el gestor de contenidos en la sección “mods”. Compila y traslada tu archivo .dll a la carpeta correspondiente del juego. Inicia el juego y comprueba como en el gestor de contenidos, aparece la nueva modificación que has creado.


1.5 Hola mundo.

A la hora de desarrollar una modificación es importante que tu código sea capaz de enviarte mensajes mientras se ejecuta. El juego posee una consola que podemos abrir pulsando F7 y con la siguiente función podemos hacer que nuestro código muestre texto en dicha consola:

Código: Seleccionar todo
 DebugOutputPanel.AddMessage(PluginManager.MessageType.Message, "El texto a mostrar por consola.");


Para el uso de “PluginManager…” es necesario añadir la siguiente directiva:

Código: Seleccionar todo
 using ColossalFramework.Plugins;


Y asegurarnos que el proyecto de Visual Studio tiene configurada la referencia a la librería ColossalManaged.dll

Recuerda que el uso de este tipo de mensajes está destinado exclusivamente para la fase de desarrollo del proyecto o para dar más información en caso de errores. Cuando termines tu modificación y decidas pasar a una fase de producción no olvides eliminar todos los envíos de este tipo de mensajes que puedas.

Continuando con nuestro ejemplo, vamos a hacer que cuando se cargue el juego y se active nuestra modificación, esta nos muestre un mensaje por consola. De la misma forma cuando se desactive nos mostrará otro mensaje distinto.

Esta tarea la vamos a realizar sobreescribiendo las funciones OnEnabled() y OnDisabled() heredadas del módulo IUserMod, es decir añadimos las siguientes líneas al cuerpo de la clase “NombreProyectoInfo”:

Código: Seleccionar todo
public void OnEnabled() {           
   DebugOutputPanel.AddMessage(PluginManager.MessageType.Message, "Hola Mundo!!!");
}
public void OnDisabled() {
   DebugOutputPanel.AddMessage(PluginManager.MessageType.Message, "Adios Mundo...");
}



Ahora compilamos, copiamos nuestra nueva .dll a la carpeta del juego correspondiente, iniciamos el juego, abrimos la consola y comprobamos como aparecen nuestros mensajes cuando activamos o desactivamos nuestra modificación en el gestor de contenidos.


Cabe destacar la importancia de saber que sobreescribiendo las funciones OnEnabled() y OnDisabled() tenemos acceso a ejecutar el código que queramos en los momentos en que el juego active o desactive nuestra modificación. En este caso lo que hacemos es que se muestre un mensaje por la consola, pero podría hacerse, por ejemplo, que cuando se active la modificación, se añada un nuevo botón al menú principal del juego, o se reproduzca un sonido, o cargue ciertos datos de fuentes externas, etc...

1.6 Resumen.

- Carpeta donde instalar los mods: “...\Cities_Skylines\Addons\Mods\”
- Carpeta de librerías del juego: “...\Cities_Skylines\Cities_Data\Managed\”
- Librerías más usadas:
    - ICities.dll
    - Assembly-CSharp.dll
    - ColossalManaged.dll
    - UnityEngine.dll
    - UnityEngine.UI.dll

- Herramientas:

- Visual Studio:
    - Nuevo proyecto: File > New > Project…
    - Tipo de plantilla: C# - Class Library
    - Compilar: Build>Build Solution
    - Cambiar de framework: (Project> NameProject Properties…) ->“Application” -> “Target framework:” [.Net Framework 3.5]

- Código C# - HolaMundo:

Código: Seleccionar todo
 
using System;
using ICities;
using UnityEngine;

using ColossalFramework.Plugins;

namespace HolaMundoMod {
   public class HolaMundoInfo : IUserMod {
      public string Name {
         get { return "Hola Mundo"; }
      }
      public string Description {
          get { return "Modificación de ejemplo"; }
      }
      public void OnEnabled() {           
        DebugOutputPanel.AddMessage(PluginManager.MessageType.Message, "Hola Mundo!!!");
      }
      public void OnDisabled() {
         DebugOutputPanel.AddMessage(PluginManager.MessageType.Message, "Adios Mundo...");
      }
   }
}



PD: Próximamente el capítulo 2: "Investigando. Desbloquear calles básicas."
Avatar de Usuario
wyllman
Turista
Turista
 
Mensajes: 40
Registrado: 30 May 2010, 21:15
Género:

Re: [Tutorial] CiSk - C# Modding: 001 - Primeros pasos

Notapor benzoll » 22 Jul 2015, 02:20

Espectacular tutorial. =P~
Chapo. =D>
Avatar de Usuario
benzoll
Ciudadano
Ciudadano
 
Mensajes: 378
Registrado: 08 Mar 2013, 19:23
Ubicación: Asturias
Género:

Re: [Tutorial] CiSk - C# Modding: 001 - Primeros pasos

Notapor benzoll » 26 Jul 2015, 17:17

Imagen
Bueno, esto funciona, ahora solo hace falta lo mas difícil: darle contenido. :P
Avatar de Usuario
benzoll
Ciudadano
Ciudadano
 
Mensajes: 378
Registrado: 08 Mar 2013, 19:23
Ubicación: Asturias
Género:

Re: [Tutorial] CiSk - C# Modding: 001 - Primeros pasos

Notapor wyllman » 26 Jul 2015, 18:08

jejejejeje me alegro mucho, hay muchas cositas que ir viendo para hacer buenas modificaciones, pero poco a poco iré sacando más capítulos, los primeros seran un poco lentos, tengan paciencia jejeje. Les animos a comentar sus avances y dudas, a ver si entre todos podemos hacer una buena recopilación de documentación.

Un saludo y suerte con el código.
Avatar de Usuario
wyllman
Turista
Turista
 
Mensajes: 40
Registrado: 30 May 2010, 21:15
Género:


Volver a Modding

¿Quién está conectado?

Usuarios navegando por este Foro: No hay usuarios registrados visitando el Foro y 1 invitado

Comunidad Capital Sim (2003-2008) webmaster arroba capitalsim.net