Difference between revisions of "SKSE Plugin Development"

Revision as of 20:04, 18 May 2019

The Skyrim Script Extender (SKSE) is a tool that expands scriptings capabilities and adds additional functionality to the game, as well as allowing modders to create plugins to further extend Skyrim's scripting capabilities. SKSE plugins take form as DLLs files that implement new functions into Papyrus, Creation Kit's scripting language. As you may guess, making an SKSE plugin is more difficult than a standard mod but the benefits of doing one are far greater. This guide focus on implementing new functions into Papyrus Scripting and debugging them.

This page is actually incompleted as it doesn't actually provide a complete tutorial on how to make an SKSE plugin project. We try to figure out how to do it ourselves before guiding others, with our only sources being closed threads, incomplete guides and tutorials who never saw any updates. With any progression on our side will come further upgrade, until this guide is completed. Until then, be assured that everything that has already been laid out is correct and up-to-date.

Sources

These are related sources that have inspired this guide. Please note that the instructions may differ from one source to another and that some might simply be completely wrong/outdated.

Zartar's "noob tutorial" on Bethesda's old forum. The whole discussion may contain other helpful information too.
Ryan-rsm-McKenzie's Tutorial on GitHub. However, his tutorial doesn't work for many users which led to believe it might be outdated.

This Reddit discussion

This GitHub page

Credit goes to Bethesda, the SKSE Team, Ryan/Fuggyduff and every contributor of this page: Dienes, ThighNookNoodel and 3Nd_R1m.

Requirements

Skyrim Special Edition
SKSE for Skyrim SE (Also referred as SKSE64)
SKSE64 source code which is included in the SKSE64 distribution
SKSE64 example plugin which should be included with the source code but actually isn't. A replacement one will be provided as soon as possible.
Visual Studio 2019, but you can use an earlier version if you wish.
And most importantly, you need to know C++ programming.

To eliminate any potential trouble, be sure to have the most up-to-date versions of Windows, Skyrim Special Edition and any other toolset specified in this guide. Please keep in mind that this guide does not guarantee Backward/forward compatibility.

Setups

Before making a plugin, you need to set up the environment.

Building SKSE

To make a plugin we'll first need SKSE's source code. However, SKSE was made with an earlier version of Visual Studio and still use outdated toolsets that aren't available within VS2019. Therefore additional setups must be performed.

Within the SKSE zip files obtained from the official website locate and extract the src/ directory.
Open the SKSE64 solution src\skse64\skse64.sln with Visual Studio 2019. VS2019 should already be associated with the .sln file type.
Upon loading, you'll be prompted with the option to "Permanently remove source control association bindings". The SKSE team uses what is called "Source control", which is a way to share, update and checkout codes coming from multiple users. We won't (and can't) use their source control so we can permanently remove any source control association. (image)
Just after that, a new window will appear and suggest to Retarget the Projects. The default options should be good enough and you can press "Ok". (image)
Why is that?

The SKSE project is made with an earlier version of the Visual C++ platform toolset (The 2015 version, there for two major versions behind). It's good development practice to keep your project's component up-to-date and, hopefully, Visual Studio can take care of that itself. However, some more configuration will be needed to successfully build the solution.
Open the Property Pages for all projects.
We're gonna tweak some options within the Configuration Properties.

You can do so by selecting all projects within the solution explorer (Tip: select the first element and then the last one while holding SHIFT ) and press ALT+ENTER to open the Property Pages.

Also make sure that the Configuration field is set to All Configuration, as we want them to apply for Debbug+ing as well as releasing.
1. Disable post-build events
  The project files include post-build events that we don't want (Such as automatically moving files into Skyrim's directory).
  
  To disable post-build events, navigate to Build Events => Post-Build Event and change the Use in build field to No.
2. Set C++ Language Standard
  Navigate to C/C++ => Language and set C++ Language Standard to ISO C++17 Standard (/std:c++17).
3. Force-include <string>
At this point, any attempt to build the solution will fail and there will be many errors 3275 (image), with the most predominant one being C2039: 'string' is not a member of 'std'. In other words, many files are using the 'string' class without including the required header to do so.

You can fix this without manually adding #include directives by instead navigating to C/C++ => Advanced and adding "string" (without quotation) in the Force Include File field. This will automatically include the string header whenever it's required.
1. Click "Apply" and then "Ok". (Image)

SKSE should be ready to build. To test that, build the solution with the Release configuration. If no error occurs, congratulation! We can move on to the next section.

Testing the build

This section is optional and aims to further validate our home-built SKSE by testing it. Assuming you already have SKSE installed, go ahead and replace the original files from the Skyrim SE directory with the new ones located in src/skse64/x64/Release. The files to replace are skse_(version).dll, skse_loader.exe and skse64_steam_loader.dll. After replacing them, try to run skse_loader.exe. Skyrim should launch without any issues.

Note: Hypothetically, an SKSE built with updated configurations may give better performance than the default one provided by the SKSE team, but the opposite may also be true.

What next?

At this point, we should start making a plugin from the SKSE example plugin. However, the project isn't present in the downloaded files, unlike what it's being said in readme.txt and PluginApi.h. In the meantime, you can take a look at our sources and look for guides who do have plugin examples.

@@ Line 1: / Line 1: @@
-===Legacy Article===
+The Skyrim Script Extender (SKSE) is a tool that expands scriptings capabilities and adds additional functionality to the game, as well as allowing modders to create plugins to further extend Skyrim's scripting capabilities. SKSE plugins take form as DLLs files that implement new functions into Papyrus, Creation Kit's scripting language. As you may guess, making an SKSE plugin is more difficult than a standard mod but the benefits of doing one are far greater. This guide focus on implementing new functions into Papyrus Scripting and debugging them.
-SKSE supports loading mod dll plugins to extend its abilities. Making a DLL plugin mod is more complicated than a standard skyrim mod with the creation kit and papyrus however it allows much greater control of the game. Since 1.07.0 SKSE has had support for adding papyrus functions in a DLL which is what this page will focus on. It does not support dynamically adding additional functions to existing scripts so you need to make a new script type as a wrapper for the new functions and then call them through that. So instead of SomeObjectReference.newFunction(param1, param2) you do NewWrapperScript.newFunction(SomeObjectReference, param1, param2).
+This page is actually '''incompleted''' as it doesn't actually provide a complete tutorial on how to make an SKSE plugin project. We try to figure out how to do it ourselves before guiding others, with our only sources being closed threads, incomplete guides and tutorials who never saw any updates. With any progression on our side will come further upgrade, until this guide is completed. Until then, be assured that everything that has already been laid out is correct and up-to-date.
-This is a quick placeholder to get things started, hopefully others will help format it and fill it out. Zartar wrote up a good guide in one of the SKSE threads that should be a base. http://forums.bethsoft.com/topic/1496168-wipz-skyrim-script-extender-skse/page-4#entry23595441 which should go here.
+== Sources ==
-There is more discussion before and after that post that would probably be helpful too.
+These are related sources that have inspired this guide. Please note that the instructions may differ from one source to another and that some might simply be completely wrong/outdated.
-A few other things that I think were talked about in a different version of the thread: SKSE only builds as is in vs2008 (the same version as skyrim was built in which helps compatibility) but plugins should be buildable in newer. Or at the least you can write in 2013+ and switch to compile them. I think you also need to modify the SKSE solution properties to suit your system for it to work but its been a long time. The function flag kFunctionFlag_NoWait in the example means the function is threadsafe so you probably don't want it. When built in debug mode SKSE has hooks to attach a debugger but it happens before the dll mods are loaded so you won't be able to break in your code that way. It is possible to attach the debugger and use breakpoints in your plugin's code but the only way I know of I don't think is appropriate to discuss as its grey area towards piracy stuff. For debugging I suggest you throw print statements in your plugin and then look at the log.
+* [http://forums.bethsoft.com/topic/1496168-wipz-skyrim-script-extender-skse/page-4#entry23595441 Zartar's "noob tutorial" on Bethesda's old forum.]  The whole discussion may contain other helpful information too.
+*[https://github.com/Ryan-rsm-McKenzie/CommonLibSSE/wiki Ryan-rsm-McKenzie's Tutorial on GitHub]. However, his tutorial doesn't work for many users which led to believe it might be outdated.
+[https://www.reddit.com/r/skyrimmods/comments/bmg1z7/finally_aiming_for_my_first_skse_plugin_been/ This Reddit discussion]
+*[https://github.com/xanderdunn This GitHub page]
-===Update 10.05.2019===
+Credit goes to Bethesda, the SKSE Team, Ryan/Fuggyduff and every contributor of this page:  Dienes, ThighNookNoodel and 3Nd_R1m.
-The following instructions are based on a Reddit discussion [https://www.reddit.com/r/skyrimmods/comments/bmg1z7/finally_aiming_for_my_first_skse_plugin_been/ over here]. The first section will cover proper setup of the Visual Studio enviroment, and the corresponding toolset, as well as a FAQ. All of the content of downloaded files, this Wiki page, and any information resources, will need to have credits dirrected towards Diens, Ryan/Fuggyduff, the SKSE-Team, and Bethesda. I'm merely trying to condense information in one place. Also, pay attention to legacy information in regard to SKSE plugin creation[https://github.com/xanderdunn Xanderdunn]. This page still gets frequented with new updates, and sometimes answering error reports.
+=== Requirements ===
+* Skyrim Special Edition
+* [https://skse.silverlock.org/ SKSE for Skyrim SE] (Also referred as SKSE64)
+* SKSE64 source code which is included in the SKSE64 distribution
+* SKSE64 example plugin which ''should'' be included with the source code but actually isn't. A replacement one will be provided as soon as possible.
+*[https://visualstudio.microsoft.com/vs/ Visual Studio 2019], but you can use an earlier version if you wish.
+*And most importantly, you need to know C++ programming.
-===Preamble===
+To eliminate any potential trouble, be sure to have the most up-to-date versions of Windows, Skyrim Special Edition and any other toolset specified in this guide. Please keep in mind that this guide does not guarantee Backward/forward compatibility.
-The following instructions assume you are modding on the most up to date versions of operating system, toolsets, and Skyrim Special Edition. The instructions may, or may not be backward/forward compatible. For the sake of sanity I'll only focus on present compatibility, since the chances for big new updates on SSE, W10, and VS may not be relevant to future .dll development.
+== Setups ==
+Before making a plugin, you need to set up the environment.
-===Requirements:===
+=== Building SKSE ===
-*Windows 10, Skyrim Special Edition, [https://visualstudio.microsoft.com/de/downloads/ Visual Studio 2019], [https://skse.silverlock.org/ SKSE64 Source], [https://github.com/Ryan-rsm-McKenzie/ExamplePlugin-SKSE64 Ryan's Plugin Example Source]
+To make a plugin we'll first need SKSE's source code. However, SKSE was made with an earlier version of Visual Studio and still use outdated toolsets that aren't available within VS2019. Therefore additional setups must be performed.
-*Optional: If you had previously installed a Visual Studio SDK, you can deinstall it with using the [https://github.com/Microsoft/VisualStudioUninstaller/releases Visual Studio Uninstaller Tool]. Additionally you can manually browse your hard drive folders, to scan for any dead remnants of older VS versions, and delete them. You may also scan the registration for any remnants, and have them deleted. It has come to my attention, that there might be problems with remnants of older VS SDK's
+#Within the SKSE zip files obtained from [https://skse.silverlock.org/ the official website] locate and extract the '''src/''' directory.
+#Open the SKSE64 solution '''src\skse64\skse64.sln''' with Visual Studio 2019. VS2019 should already be associated with the .sln file type.
+#Upon loading, you'll be prompted with the option to "Permanently remove source control association bindings". The SKSE team uses what is called "Source control", which is a way to share, update and checkout codes coming from multiple users. We won't (and can't) use their source control so we can permanently remove any source control association. [https://imgur.com/95b5KXK (image)]
+#Just after that, a new window will appear and suggest to Retarget the Projects. The default options should be good enough and you can press '''"Ok"'''. [https://imgur.com/jnyPSWk (image)]
+#; Why is that?
+#: The SKSE project is made with an earlier version of the Visual C++ platform toolset (The 2015 version, there for two major versions behind). It's good development practice to keep your project's component up-to-date and, hopefully, Visual Studio can take care of that itself. However, some more configuration will be needed to successfully build the solution.
+#Open the Property Pages for all projects.
+#: We're gonna tweak some options within the Configuration Properties.
+#: You can do so by selecting all projects within the solution explorer (Tip: select the first element and then the last one while holding '''SHIFT''' ) and press '''ALT'''+'''ENTER''' to open the Property Pages.
+#: Also make sure that the '''Configuration''' field is set to '''All Configuration''', as we want them to apply for Debbug+ing as well as releasing.
+## Disable post-build events
+##: The project files include post-build events that we don't want (Such as automatically moving files into Skyrim's directory).
+##: To disable post-build events, navigate to '''Build Events => Post-Build Event''' and change the '''Use in build''' field to '''No'''.
+## Set C++ Language Standard
+##: Navigate to '''C/C++ => Language''' and set '''C++ Language Standard''' to '''ISO C++17 Standard (/std:c++17)'''.
+## Force-include <string>
+#: At this point, any attempt to build the solution will fail and there will be many errors [https://imgur.com/9jpNjtK 3275 (image)], with the most predominant one being <q>C2039: 'string' is not a member of 'std'</q>. In other words, many files are using the 'string' class without including the required header to do so.
+#: You can fix this without manually adding #include directives by instead navigating to '''C/C++ => Advanced''' and adding "string" (without quotation) in the '''Force Include File''' field. This will automatically include the string header whenever it's required.
+## Click "Apply" and then "Ok". [https://imgur.com/4DWpnzP (Image)]
-===Installing Visual Studio 2019===
+SKSE should be ready to build. To test that, build the solution with the Release configuration. If no error occurs, congratulation! We can move on to the next section.
-[https://docs.microsoft.com/en-us/visualstudio/install/install-visual-studio?view=vs-2019 Official Microsoft Install Instructions]
+==== Testing the build ====
+This section is optional and aims to further validate our home-built SKSE by testing it.
+Assuming you already have SKSE installed, go ahead and replace the original files from the Skyrim SE directory with the new ones located in '''src/skse64/x64/Release'''. The files to replace are '''skse_(version).dll''', '''skse_loader.exe''' and '''skse64_steam_loader.dll'''.
+After replacing them, try to run '''skse_loader.exe'''. Skyrim should launch without any issues.
-*Installing on system drive C: is personal preference, and primarly done for convenience during install procedure
+Note: Hypothetically, an SKSE built with updated configurations may give better performance than the default one provided by the SKSE team, but the opposite may also be true.
-*Depending on your choice of install range, Visual Studio 2019 may need disk space ranging from anything of 600MB to 25GB, depending on the components you want to install. Installing on a SSD, or any faster equivalent, is recommended
-*Refer to [https://imgur.com/0orcc3K this image], for an example on personal preference
-*If you are not on a native English OS, make sure to additionally select and install the English language pack for VS2019, if you want to stay consistent with general coding language
-*Make sure to install/run VS2019 as administrator!
-===Setting up SKSE64 Source===
+== What next? ==
-*Most, if not all the instructions on this article, is based on the users's [https://github.com/Ryan-rsm-McKenzie/CommonLibSSE/wiki/Getting-Started Ryan instructions]
+At this point, we should start making a plugin from the SKSE example plugin. However, the project isn't present in the downloaded files, unlike what it's being said in readme.txt and PluginApi.h. In the meantime, you can take a look at our sources and look for guides who do have plugin examples.
-#Download [https://skse.silverlock.org/ SKSE64 Source], and [https://imgur.com/9gp8fwv unpack the .zip] to a folder of your choice. Make sure to backup/seperate, if you also utilize SKSE64 for your game
-#Open up the file '''src\skse64\skse64.sln''', by double clicking, then [https://imgur.com/95b5KXK permanently removing source control]
-#You may now [https://imgur.com/jnyPSWk upgrade the SDK/toolset]. I encourage you to do so, because this tutorial is based on upgraded toolset files. According to Ryan you do <u>not</u> necessarily need to do this
-#Ensure you're [https://imgur.com/AmSK7l2 building in Debug mode]
-#Direct quote of Ryan: [https://imgur.com/GFcfIJT "Disable SKSE's post-build events] by selecting all projects, right click -> Properties -> Configuration Properties -> Build Events -> Post-Build Event -> Use In Build -> No. SKSE's build events are configured for their environment, however ours is different, so we won't be using them"...you can select all by using CTRL+left click
-#Make sure these changes apply to [https://imgur.com/4DWpnzP all configurations]
-From here the original instructions of Ryans tutorial differed for me. That may not be the case for you. I encountered a problem, when trying to build the SKSE64 .dll, that resulted in [https://imgur.com/9jpNjtK 3275 error messages]. A trace to why this is happening can be found [https://www.reddit.com/r/skyrimmods/comments/bmg1z7/finally_aiming_for_my_first_skse_plugin_been/emym7d9?utm_source=share&utm_medium=web2x here]. Basically this happens, because the latest SKSE source did not include a particular string library, which you will have to add manually, after upgrading SKSE64 to VS2019 (See section '''"Fixing error C2039"'''). So this means from here I assume you will stay with VS2017. Don't be worried, since the following instructions will apply to both VS versions.
-#Multi select all projects with CTRL+ left click, then right click->Properties->Configuration Properties->C/C++->Language and make sure to select the correct [https://docs.microsoft.com/en-us/cpp/build/reference/std-specify-language-standard-version?view=vs-2019 C++ ISO standard(v17)]
-#After confirmation open properties again for all projects, and make sure to->Configuration Properties->General->Platform Toolset->set to '''Visual Studio 2017(v141)'''
-#Optional: set to Visual Studio 2019(v142), if you've already gone ahead, upgraded to VS2019, and fixed the previously mentioned SKSE64 string problem
-#Now the essential trouble fixing part: this information depends on if you either have VS2017, or VS2019 installed. In the Configuration Properties->General section make sure to <u>not</u> use the latest Windows SDK Verion, which is clearly labeled with "latest/updated". You want to use the SDK with version ID: '''10.0.18362.0''' for VS2017. This might not be true when using VS2019.
-If you deliberately want to use the most up to date SDK, there's traces either on any of the Nexus pages, or Github pages for SKSE64 .dll content creators, that have gone through upgrading SKSE64 for VS2019. You might want to contact [https://www.nexusmods.com/users/2025634 Aers], or Ryan in order to get closer information on this, and maybe even obtain a SKSE64 source for VS2019? I'm also uncertain if the SKSE team did already update the latest SKSE64 source to use the latest SDK update, or plan to do so for the next SKSE64 update. As it stands now, due to my findings, it's entirely possible SKSE team did not even upgrade to VS2017 yet, and were using VS2015 for the latest SKSE64 update.
-===Fixing error C2039: 'string' is not a member of 'std'===
-At this point any attempt to build the solution will fail and there will be many errors, with the most predominant one being `C2039: 'string' is not a member of 'std`. One way to fix it is to include <String> in the following files:
-*common_vs14/IDirectoryIterator.h
-*skse64-commons/Relocation.h
-*skse64_loader_common/IdentifyEXE.h
-*skse64_loader/Options.h
-You can do so by pasting this lines:
-`#include <String>`
-SE build 2.0.15: You will see 'C26495' warnings in the error list. Those warnings are for the SKSE team to fix and you can safely ignore them.
-===FAQ===
-'''Why should I use VS2019/2017?'''
-According to Ryan, the intern versioning does not really matter. What matters, is the amount of bugs you'll have to fix when upgrading to any new VS version, if you haven't previously updated. Also, any new VS version will be more powerful and user friendly to utilize. So it's basically just a question of convenience, to improve workflow. On the topic of SKSE64 potentially created with VS2015: It's just what I assume, since that's what the files tell me. If you know it better, let me know, so I stand corrected.
-'''You're constantly hopping in between the different VS versions, in your instructions. You are confusing me!?'''
-Guess what. That's because the whole setup of VS was nothing but a giant and thoroughly confusing pita on my end. But getting the SKSE64 source to run and compile with VS2019 made me tear out my hair. However, for you the following things are important:
-*Visual Studio 2019
-**Windows SDK 10.0(most up to date)
-***Platform Toolset Visual Studio 2019(v142)
-****C/C++ ISO standard v17
-*Visual Studio 2017
-**Windows SDK 10.0(10.0.18362.0)
-***Platform Toolset Visual Studio 2017(v141)
-****C/C++ ISO standard v17
-*Visual Studio 2015
-**Windows SDK 8.1(???)
-***Platform Toolset Visual Studio 2015(v140)
-****C/C++ ISO standard v14
-'''Why do you keep mentioning different versions of Visual Studio? I do have VS2019 installed, right?'''
-That's correct. But you can freely switch between VS2017/VS2019 in the latest VS2019 install. You can also switch even further back to VS2015, but you will need to figure a way to get access to the Windows 8.1 SDK for this. And as far as I'm aware, the only direct access is either by installing Visual Studio 2015, or Windows 8.1. None of those cases are true for the instructions provided in this article.
-'''What's with the initial article made by Dienes, and why don't you make your own article?'''
-The original info is outdated, but links back to the very beginnings in 2012. So you might still want to follow the provided link to learn something additional. Also, the create article button simply doesn't show up on any of the Wiki's pages, for me.
-'''Any more relevant discussions happening?'''
-Yes: [https://www.reddit.com/r/skyrimmods/comments/bmg1z7/finally_aiming_for_my_first_skse_plugin_been/ here], [https://www.reddit.com/r/skyrimmods/comments/bmwjjt/tutorialcreating_skse_dll_plugin_setting_up_the/ here], and on the [https://discord.gg/fmEKvBN Discord]
-'''I still get various error reports, even after successful compiling the SKSE64 source!!!'''
-Refer to [https://github.com/Ryan-rsm-McKenzie/CommonLibSSE/wiki/Getting-Started Ryan's instructions] to solve or ignore.
-'''Can I find any trace inside source files, on which version was used to compile?'''
-Nope, haven't found any. However, Github actually provides this information inside the '''.gitignore''' file, and most of the sources are actually provided on Github. However, there's usually info provided inside the '''.vcxproj''' files, which toolset has been used, which in return might provide the info which version of Visual Studio was used.
-===Addendum===
-Section two will cover on working with a [https://github.com/Ryan-rsm-McKenzie/ExamplePlugin-SKSE64 plugin example] based on the install posted upside. Until I'm going to update this article, you should use Ryan's tutorial over on Github as resource. It's probably best practice anyways, since he's not as much a chatterbox, than I am. Pay special attention to the Debugger section. Without this, you will never be successful.