[SA] Texture Fun using plugin-sdk

[The_GTA]

In this thread I want to show you how to make good use of RenderWare textures in your custom .ASI plugin. I will present examples and explain how they work, so you can play around and maybe create even more awesome things.

 

We are using plugin-sdk by DK22Pac (and others).

 

Things you will need:

• Microsoft Visual Studio 2017
• TortoiseSVN (highly recommended)
• Magic.TXD (for creating .rwtex files)
• Ultimate ASI loader (for loading our .ASI plugin)
• Grand Theft Auto San Andreas 1.0 US
• C++ programming experience (if you want to edit the .ASI)
• Determination.

The GTA:SA engine was developed based on the powerful RenderWare3 framework. It enables us to put plugins on top of the game without hooking too deep. A good example is the RenderWare texture environment. Textures are everywhere, from the HUD to the menu and the radar. When the game needs a texture, it asks the currently loaded TXD archive using a character-sequence key. Textures usually travel in TXD files, but I want to show you an easier way so you can store textures directly on your harddisk, skipping TXD files completely (.rwtex files).

 

It is up to your imagination and capability what you can make out of this. Let's get started.

 

 

Example 1: Drawing Textures on Screen.

 

 

source code: http://eirasi.osdn.jp/Projects/sarwtexload.html

 

For an easy introduction let's first try drawing a RwTexture onto screen. The idea is to put the texture into Rockstar North's CSprite2d class and draw it each frame, as long as we want to. Thanks to DK22Pac's plugin SDK this process is really simple, and by exploring plugin-sdk we can get a good understanding of the GTA:SA engine.

 

Setting up the codebase(s)

Once you have installed all the necessary tools it is really easy to set up the codebase.

 

First you have to go to your desktop and right-click on empty space. This will open the explorer context menu where you will find the TortoiseSVN shell options. We want to "SVN Checkout..." our code repository.

 

You will be presented with the SVN Checkout dialog. The most important field in this dialog is the "URL of repository:" edit box. We want to fill this with the special URL that we get from our code repository. Let's head to our repository now.

 

Select the text of "Check-out URL" line and press CTRL+C. Optionally you can right click and copy. You want to paste this URL into the "URL of repository:" edit box in the dialog we opened earlier. Once you did that, the "Checkout directory:" edit box should be filled automatically with the appropriate target folder.

 

Finally, click on "OK". This will download the code repository on your computer.

 

Next thing is getting accustomed with our repository. Each repository I will show you in this thread will follow the same layout, so don't worry

• build: this folder contains the project files to build our plugin. we first have to compile the plugin-sdk before we can build the plugin
• depends: in here you will find dependencies, like the plugin-sdk by DK22Pac. you want to build the dependencies first.
• include: you should find .h files in this folder, if it is used. those are headers for your plugin, if the plugin is complicated. for our purposes this folder is often empty or non existant.
• src: this folder contains the actual executable code of our plugin, like the "main.cpp" file that contains the real meat, aside from what we build on!

I suggest you explore each folder, and return to the root when done. We first want to go into "depends/plugin-sdk/trunk". We need to generate build files using premake5 for the compiler we want to use (MSVC). Execute one of the provided .bat files for that. A new folder called "BUILD" should be generated in turn. Navigate into it and open the .sln file. This will open up Microsoft Visual Studio with the plugin-sdk project!

 

We want to build the plugin-sdk in Release and Debug configurations. If you are familiar with Visual Studio already this should be no problem to you. If not, simply follow the steps as they are displayed in the image. Right click on the "plugin_sa" text and select "Build", once if you have selected "Release" in the dropdown above and another time if you have selected "Debug" in the dropdown. This should create plugin(_d).lib files that are required for our .ASI plugin to function properly.

 

NOTE: some revisions of the plugin-sdk come with pre-built .lib files. Please compile the plugin-sdk yourself anyway, because this guarrantees that you have the latest .lib files!

 

Now we want to go back to the root folder of our code repository to build our plugin. Remember that we can find the project files inside of the "build" folder so let's head there. Double click on the .sln file inside of that folder.

 

Follow the same steps for compiling the plugin as we did for the plugin-sdk. Remember to build for Release and Debug.

 

If you have not installed Ultimate ASI loader yet, now is the time. I assume you know how this works, because it is standard practice in the GTA modding community. Any good .ASI loader should work in our tutorial.

 

Last but not least, we can now install our freshly compiled plugin! You find the plugin file in the "output/Release" folder in the code repository root. Simply move the .ASI file into your GTA SA folder. You might need to put it into the "scripts" folder depending on how your ASI loader works, so be careful to read the instructions.

 

Congratulations! You can now compile and run your own .ASI plugins!

 

For the "Drawing Textures on Screen" .ASI you need to put a "test.rwtex" file into the folder of your gta_sa.exe. You can either create your own using Magic.TXD or download a sample here:

 

https://mega.nz/#!MZsBgSwC!N21RzzIqnTmSEq2woN-QgsOze6wC-pAADnO2Y72RG60

 

.rwtex files are native RenderWare texture chunks that come with rendering configurations. They are optimized to load very fast into the game in addition to supporting every color format that the game can load. It is a much more powerful format than .DDS because it can come in many platforms and with plugins.

 

 

        Events::drawingEvent += [] {            if ( drawTexSprite )            {                drawTexSprite->Draw(CRect(10.0f, 10.0f, 300.0f, 300.0f), CRGBA(255, 255, 255, 255));            }        };

This code is responsible for drawing the "test.rwtex" file on screen. By changing the numbers inside "CRect" you can move the image around. By changing the numbers inside "CRGBA" you can blend the image into a different tint of color, making it transparent or something entirely different! I suggest you try changing those values in your local copy of the plugin.

 

So, after you have finished this introductory example, you maybe want something more advanced? I have something really special for you. This next example opens up really unique modding capabilities, if you understand it's implications.

 

Example 2: Replacing game textures using RWTEX dynamically

 

 

source code: http://eirasi.osdn.jp/Projects/satexglobrepl.html

 

This is an .ASI plugin that dynamically replaces each texture that the game is asking for using one of the .rwtex files inside of your "textures" folder. In the image above I have placed a "coronamoon.rwtex" file containing the GTAnet logo. This is a perfectly optimized way to load images into GTA:SA: the game only asks for the texture once and then caches it in memory! You can even replace world model textures this way, provided that you improve its implementation to cache textures that are potentially loaded multiple times. Content creators could use this to quickly test out textures on their models before building TXD files for them.

 

To build the repository, follow the steps that were presented in Example 1. The steps are exactly the same.

 

Here is the sample .rwtex file that was used in the image above. I strongly advice you to export your own .rwtex files. Make sure you create them in Direct3D9 format!

 

https://mega.nz/#!Mc9w3baR!N4-HR6u05f-XvVXgRIYk1oQUNo_7KBvTXFHCeVGJ-NQ

 

Analyzing the Code

 

To understand what the code is doing you need a deeper understanding how RenderWare 3.5.0.0+ handles texture loading.

 

        findTexture_hook = injector::scoped_jmp( 0x007F3AC0, RwFindTexture, true );

In this code segment we hook the global RenderWare texture request function. I think in original RW this function was called "RwReadTexture", but I think you understand the concept. Usually each model has textures in TXD containers so that this function would look into the currently loaded TXD archive (linked to our model) and return a referenced handle. By hooking, we want to extend this behavior by allowing our textures to override the ones coming from any other .TXD archive!

 

 

RwTexture* RwFindTexture( const char *name, const char *maskName ){    RwGlobals *rwInterface = RwEngineInstance;    // First try to find thing in our textures     {        std::string texPath = CFileMgr::ms_rootDirName;        texPath += "textures/";        texPath += name;        texPath += ".rwtex";        if ( RwTexture *texHandle = loadRWTEXFromDisc( texPath.c_str() ) )        {            // We can just return it.            // We do not care about caching it.            return texHandle;        }    }

While I think that the entire RwFindTexture function is interesting I think that this part deserves the most attention. Here we have overridden said behavior with a dynamic filesystem lookup for a local .rwtex file. Literally every texture request is made through this function.

 

Criterion's idea was that game designers could receive feedback by analyzing how models requested textures... Maybe models were missing certain textures or multiple models shared the same one. You can analyze this behavior by putting a breakpoint in certain places of RwFindTexture.

 

 

So that is all for now. I hope you enjoyed this little tutorial of mine and have further desire to mod GTA:SA using DK22Pac's plugin-sdk. It is a really great framework because you do not have to write anymore assembly code! Give it a try.

 

If you read through this tutorial, thank you very much.

 

Thanks to...

• DK22Pac, LINK/2012 and others for plugin-sdk
• iFarbod for idea to render with CSprite2d
• ThirteenAG for his really useful windowed mode ASI

Edited August 30, 2017 by The_GTA

[iFarbod]

AMAZING, I'm using RWTEX' power in SAO

[The_GTA]

I have updated the samples to directly point to DK22Pac's plugin-sdk repository on GitHub. If you have any questions or feedback about compiling and using it post on his GitHub repo page

Edited May 15, 2016 by The_GTA

[HeresOtis]

Can Renderware draw text?

[The_GTA]

Can Renderware draw text?

You can map your custom FreeType text output engine onto RenderWare rasters and then use U/V coordinate lookup to draw character quads on the screen. It is a challenging learning experience that unfortunately goes out of scope of this thread, because I present native RenderWare methods here.

 

I think you may be asking about RenderWare itself. No, it does not provide text rendering. Imagine that RenderWare3 was designed in the 90s and back then Unicode was a luxurious thing. But you may be getting what you want in this thread by Shmoopy. Even if using an older SDK I am pretty sure the GTA:SA objects use the same method names.

 

If you are asking me for another tutorial... won't be doing any for now. Need to concentrate on other things

[Sloth-]

 

We want to build the plugin-sdk in Release and Debug configurations. If you are familiar with VS2015 already this should be no problem to you. If not, simply follow the steps as they are displayed in the image. Right click on the "plugin_sa" text and select "Build"

 

I did that and i'm getting this error

 

 

 

I google'd the '/game_sa/CRunningScriptWrapper.cpp', and i found this.

Why is a necessary project file in a mirror and not in the original source?

 

also, instead of compiling my own plugin.lib, i downloaded it from this topic, and i placed inside the '\trunk\output\lib\plugin_sa\Release\' folder, and then i added as 'existing item' in the 'sa_rwtex_loader' project but i couldn't compile it.

 

Help!

 

 

EDIT:

Sorry, i just had to remove those "ghost" files "game_sa/CRunningScriptWrapper.cpp" and "/ScriptCommands.cpp", and the plugin now compiles fine.

But i still have the doubt about why those files appeared...

Edited May 31, 2016 by Sloth-

[Sloth-]

New issue:

 

In second example (sa_rwtex_repl_global):

 

'MyRwEngineInstance': undeclared identifier

 

 

If we are managing the same files, why is this happening to me?

[The_GTA]

I will take a look at it soon when I come home from University!

afk...

I would like to add you to Skype about this issue so please send your contact details to my inbox.

---------------------------------

I have analyzed the issue. It turns out that somebody has messed up a commit on plugin-sdk:

https://github.com/DK22Pac/plugin-sdk/commit/3bcc5c8d776aeb8258916310d4ca031448fca7da

We have to wait for the guy to get his files uploaded to the plugin-sdk repository. A temporary work-around is to remove the offending files from the plugin-sdk project solution (temporarily).

ScriptCommands.cpp
ScriptCommands.h
game_sa/CRunningScriptWrapper.cpp
game_sa/CRunningScriptWrapper.h

---------------------------------

If anyone is wondering why issues appear, it is because plugin-sdk is being maintained by some people and not all of them do their job correctly. People do mistakes.

 

EDIT. the issues with missing files have been fixed by Dmitry himself. If any future issues of same calibre appear, you guys know what to do.

Edited June 6, 2016 by The_GTA

[Sloth-]

So that was the problem.

 

I'm also trying this tutorial, but his steps are giving me errors too.

 

I hope files get fixed soon, i'm very excited about learning asi coding.

Edited May 31, 2016 by Sloth-