Adam's Lair Forum

game development and casual madness
It is currently 2020/01/28, 18:17

All times are UTC + 1 hour [ DST ]




Post new topic Reply to topic  [ 11 posts ]  Go to page 1, 2  Next
Author Message
PostPosted: 2015/09/13, 14:52 
Site Admin
Site Admin
User avatar

Joined: 2013/05/11, 22:30
Posts: 2073
Location: Germany
Role: Professional
Hello everyone,

in this posting, I'll try to guide you through the process up upgrading your existing Duality project from v1.x to v2.0.

I'll assume that you are using the binary version of Duality and not building it yourself - however, most of these steps are applicable in the same way, and if you're using a custom build, you likely know where the differences are and how to account for them.

Note: At the time of this posting, v2.0 binaries are not yet released. You'll know when they are. ^^

Before We Begin

First of all, you should carefully consider upgrading. It's not a click-here-and-done thing and you should pick a date where you actually have some extra time to invest. It may take a day or two for large projects and include both manually fixing Resources and porting your game plugin source code to the latest APIs.

There is no rush in doing this - Duality won't push you to auto-update and in fact, you could just leave your project on v1.x indefinitely. The only disadvantage is that, with the release of v2.0, there won't be any more updates for v1.x and community support will be less ad less applicable, as we all move on. If you're close to finishing your project, you might just not update at all. If you've just started something new, updating should be a valid concern.

Preparation

First of all, you should make a full backup of your project if anything fails. This is important. If you're on a version control system, you might consider creating a new branch for the update progress.

Next, open the editor and make sure all Resources are saved in the XML format, so we can edit them by hand later. There's a button in the upper right to switch serialization formats, which also allows you to re-save all Resources. Select XML (if it isn't already, it's the default) and then Update All.

Updating the Framework

Open the Package Manager and update all installed packages to the new v2.0 release. All of them. The Package Manager might tell you that this is not a recommended operation due to potentially breaking changes, but we already know that. This is what we came to expect. After the packages are downloaded, do not restart the editor yet. We're not done yet.

If you are using third-party packages that don't yet have a new release version for v2.0, that's very likely a problem. Your options are:

  1. Checking if the package is open source, fork it and manually port it to v2.0, then set up a local package repository with you own custom, updated version in it and use that.
  2. Message the package author and ask him to provide a new v2.0 version of the package.
  3. Get rid of the package dependency and replace it with something else.
  4. Don't update yet.

But, for the sake of this tutorial, let's hope that this is not the case. What we need next are some new packages that didn't exist in v1.x and thus didn't come with the updated v2.0 package versions: You're going to need some backend packages! Without them, you can still run editor and launcher, but the core won't be able to render anything, play audio, detect input or access the file system.

For now, install the following backend packages:

  • AdamsLair.Duality.Backend.DotNetFramework
  • AdamsLair.Duality.Backend.DefaultOpenTK
  • AdamsLair.Duality.Editor.Backend.DefaultOpenTK

Now we're ready to apply the update. Let the editor restart and move its new files around, but do not touch anything afterwards and close the editor again. The framework may be updated, but all your game binaries and content is not.

Upgrading your Game Plugin

This is the fun / source code / programming part. One of the big changes from v1.x to v2.0 is that all game plugins, by default, are now Portable Class Libraries using PCL Profile 111. Visual Studio doesn't seem to have a mechanism for changing a C# Class Library into a Portable Class Library, so we'll have to do this manually by editing the .csproj file:

  1. Open your game plugin .csproj file with a text editor, such as Notepad++.
  2. Insert the following block as a set of child elements into the first PropertyGroup XML element:
    Code:
    <ProjectTypeGuids>{786C830F-07A1-408B-BD7F-6EE04809D6DB};{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}</ProjectTypeGuids>
    <TargetFrameworkProfile>Profile111</TargetFrameworkProfile>
    <TargetFrameworkVersion>v4.5</TargetFrameworkVersion>
  3. Remove all other occurrences of the three elements in the file, so they don't overwrite what you've just inserted.
  4. Replace this element:
    Code:
    <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
    with this one:
    Code:
    <Import Project="$(MSBuildExtensionsPath32)\Microsoft\Portable\$(TargetFrameworkVersion)\Microsoft.Portable.CSharp.targets" />
  5. Save the file and close it.

Next, open the solution file of your game plugin in Visual Studio. The project should now have a little "(Portable)" remark in its name. Expand the project node in the tree view, as well as its References node and remove all explicit System.XY dependencies, as well as all OpenTK dependencies. Instead, add a new one to DualityPrimitives.dll in the main Duality directory.

The basic preparation of porting the game plugin project is done. All you need to do now is get it to compile again. You'll likely see a lot of errors, mostly due to the fact that a lot of Duality APIs have been moved or renamed, and a lot of OpenTK data structures are no longer used and have been replaced with custom ones from Duality.

This might take a while. Fix all the errors and compile the project. As soon as it's successful, you are ready to move on.

Upgrading your Game Content / Resources

This is basically a huge Find / Replace operation. Remember all the classes you've had to reference differently from your source code, because they have been moved or renamed? Now, the same thing needs to be done to all of your game content, i.e. all Resource files. Grab a text editor with cross-file Find / Replace features, like Notepad++ and start replacing names. I recommend the following workflow:

  1. For all the renamed Types you know of, do a Find / Replace over your whole Data directory to replace the old Type ID with the new one.
  2. Start the editor and click on a few Resources and Scenes.
  3. Open the Log View and look at the very first logged error. It likely tells you about an unknown / unresolved Type.
  4. You now know a new renamed or moved Type. Goto Step 1.

As a start, here are a few that have been moved and need to be replaced. The list is not complete, but it should cover at least a part of it:
Code:
OpenTK.Vector2/3/4
OpenTK.Quaternion
OpenTK.Matrix3/4
OpenTK.Input.Key
OpenTK.Input.MouseButton
OpenTK.Input.JoystickButton
OpenTK.Input.JoystickAxis
OpenTK.Graphics.OpenGL.TextureMinFilter
OpenTK.Graphics.OpenGL.TextureMagFilter
OpenTK.Graphics.OpenGL.TextureWrapMode
OpenTK.Graphics.OpenGL.PixelInternalFormat
Duality.SoundType
...


Finally, when all errors are fixed, you will need to re-import all Fonts you were using. Delete the Font Resources entirely and drag them into the editor again. This is necessary due to the fact that they're now editor-rendered bitmap fonts.

Final Words

You're now on v2.0. Neat! :D

This, however, is just a rough guide on how to upgrade. You might encounter problems that were not described here, in which case you will probably find a custom solution yourself. Feel free to ask for help and let others know what additional problems you encountered, and how you fixed them. Thanks! And welcome to v2.0 ^^

_________________
Blog | GitHub | Twitter (@Adams_Lair)


Top
 Profile  
 
PostPosted: 2015/09/23, 15:49 
Forum Addict
Forum Addict
User avatar

Joined: 2013/09/19, 14:31
Posts: 883
Location: Italy
Role: Hobbyist
I'm beginning to try to port my Frozen plugins to 2.0.. one thing I noticed is that it seems there is no more need to mark Components as [Serializable]. Correct?

EDIT: and how to deal with resources icons now that System.Drawing is gone? :omg: ... nvm... embedded resources :redface:

EDIT2: and now I see that MouseButtonEventArgs wants a MouseInput parameters.. what gives? :question:
EDIT3: for this, I am currently using DualityApp.Mouse.. at least it compiles. I'll know if it works later :mrgreen:

_________________
Come on Duality's Discord channel. We have cookies! :mrgreen:


Top
 Profile  
 
PostPosted: 2015/09/24, 00:13 
Site Admin
Site Admin
User avatar

Joined: 2013/05/11, 22:30
Posts: 2073
Location: Germany
Role: Professional
SirePi wrote:
I'm beginning to try to port my Frozen plugins to 2.0.. one thing I noticed is that it seems there is no more need to mark Components as [Serializable]. Correct?


Yes. Serializable isn't available in the PCL profile 111, which is now used by the core, and (by default) by all core plugins.

Instead, Duality now defines its own attributes for serialization, and while at it, switched from declaring what can be serialized to declaring what can't. As long as you don't slap a DontSerialize attribute on a class or field, the assumption will be that it can be serialized.

SirePi wrote:
EDIT: and how to deal with resources icons now that System.Drawing is gone? :omg: ... nvm... embedded resources :redface:


Yup. See the core and official repo core plugins ^^

SirePi wrote:
EDIT2: and now I see that MouseButtonEventArgs wants a MouseInput parameters.. what gives? :question:


Theoretically, it is possible to detect multiple mouse input devices. This is not currently implemented, used or tested, but parts of the API are designed in a way to not be a roadblock, in case this will be added at some point. Thus, mouse-related event arguments have a MouseInput as their source input channel, just like other inputs specify their GamePad, Keyboard or Joystick origin.

Or, in less text: Those event args want to know where the input came from.

SirePi wrote:
EDIT3: for this, I am currently using DualityApp.Mouse.. at least it compiles. I'll know if it works later :mrgreen:


If you're processing input from DualityApp.Mouse and then emit events based on that, this would seem correct to me ^^

_________________
Blog | GitHub | Twitter (@Adams_Lair)


Top
 Profile  
 
PostPosted: 2015/09/30, 21:53 
Forum Adept
Forum Adept

Joined: 2014/12/13, 00:11
Posts: 398
Location: Brazil
Role: Gamer
I have a question. Are there any major changes in the Resource class? I was trying to port my Tiled plugin to 2.0, and it is quite odd :(.
I don't know what changed exactly, and I'm lost at the moment.

_________________
I only know the basics of C#. I have no advanced knowledge.


Top
 Profile  
 
PostPosted: 2015/10/01, 11:56 
Forum Addict
Forum Addict
User avatar

Joined: 2013/09/19, 14:31
Posts: 883
Location: Italy
Role: Hobbyist
RockyTV wrote:
I have a question. Are there any major changes in the Resource class? I was trying to port my Tiled plugin to 2.0, and it is quite odd :(.
I don't know what changed exactly, and I'm lost at the moment.

I agree, I managed to deal with my basic Resources but now I'm at the point where I need to upgrade the Importers and is not too clear how to proceed with that.

_________________
Come on Duality's Discord channel. We have cookies! :mrgreen:


Top
 Profile  
 
PostPosted: 2015/10/01, 13:04 
Site Admin
Site Admin
User avatar

Joined: 2013/05/11, 22:30
Posts: 2073
Location: Germany
Role: Professional
What problems are you facing exactly? (Both of you)

_________________
Blog | GitHub | Twitter (@Adams_Lair)


Top
 Profile  
 
PostPosted: 2015/10/01, 13:53 
Forum Addict
Forum Addict
User avatar

Joined: 2013/09/19, 14:31
Posts: 883
Location: Italy
Role: Hobbyist
Adam wrote:
What problems are you facing exactly? (Both of you)

For me, it's mostly about how to manage the new IAssetImporter and having to deal without System.IO due to the portable nature of the Plugins

_________________
Come on Duality's Discord channel. We have cookies! :mrgreen:


Top
 Profile  
 
PostPosted: 2015/10/01, 14:07 
Site Admin
Site Admin
User avatar

Joined: 2013/05/11, 22:30
Posts: 2073
Location: Germany
Role: Professional
SirePi wrote:
Adam wrote:
What problems are you facing exactly? (Both of you)

For me, it's mostly about how to manage the new IAssetImporter and having to deal without System.IO due to the portable nature of the Plugins


You're writing an editor plugin here - and as the editor is Windows-only, you can use a regular non-portable class library. ^^

As a note though, in Duality's core, there still is I/O functionality even though it's portable. Use these classes:
Code:
Duality.IO.PathOp
Duality.IO.DirectoryOp
Duality.IO.FileOp
They're portable Duality equivalents of the similarly named System classes.

Edit: As far as the new IAssetImporter API goes, use the existing importers as an example.

_________________
Blog | GitHub | Twitter (@Adams_Lair)


Top
 Profile  
 
PostPosted: 2015/10/01, 15:13 
Forum Adept
Forum Adept

Joined: 2014/12/13, 00:11
Posts: 398
Location: Brazil
Role: Gamer
Adam wrote:
What problems are you facing exactly? (Both of you)


Uh, I'm facing problems such as:
- Not being able to use FileStream and System.IO classes
- SourcePath being removed, I don't know what replaced it

It's probably better to rewrite my Resource class, and reimplement my Load/Save methods.

_________________
I only know the basics of C#. I have no advanced knowledge.


Top
 Profile  
 
PostPosted: 2015/10/01, 21:00 
Site Admin
Site Admin
User avatar

Joined: 2013/05/11, 22:30
Posts: 2073
Location: Germany
Role: Professional
RockyTV wrote:
Adam wrote:
What problems are you facing exactly? (Both of you)


Uh, I'm facing problems such as:
- Not being able to use FileStream and System.IO classes
- SourcePath being removed, I don't know what replaced it

It's probably better to rewrite my Resource class, and reimplement my Load/Save methods.


Ah, in that case: See my previous answer to SirePi ^^ Importers in editor plugins can still use the full .Net framework, everything (including Resources) in core plugins should either not use I/O (when it's not crucial) or use the above mentioned Duality.IO replacement classes.

As far as SourcePath goes: No need to specify that anymore. The new AssetManagement system handles that stuff for you.

_________________
Blog | GitHub | Twitter (@Adams_Lair)


Top
 Profile  
 
Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 11 posts ]  Go to page 1, 2  Next

All times are UTC + 1 hour [ DST ]


Who is online

Users browsing this forum: No registered users and 3 guests


You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum

Jump to:  
cron
Powered by phpBB® Forum Software © phpBB Group