From 684510e2bfe1b1e7390531872377fd182c9b0cb4 Mon Sep 17 00:00:00 2001 From: Fernando-A-Rocha Date: Thu, 30 Oct 2025 14:54:34 +0000 Subject: [PATCH 01/19] WIP --- .github/doc/DOCUMENTATION.md | 22 +++--- .github/doc/MIGRATION.md | 14 ++++ README.md | 10 ++- [examples]/test_vehicles/meta.xml | 2 +- [examples]/test_vehicles/s_test_cmd.lua | 10 +-- [examples]/test_vehicles/s_vehicles.lua | 4 +- [examples]/test_vehicles/s_vehicles_alt.lua | 4 +- {newmodels_azul => newmodels_red}/meta.xml | 2 +- .../models/README.md | 2 +- .../models/object/1337/SAMP/.gitignore | 0 .../models/object/1337/SAMP/README.md | 6 +- .../models/object/1337/SAMP/sampobj.png | Bin .../models/object/1337/big_box/40001.col | Bin .../models/object/1337/big_box/40001.dff | Bin .../models/object/1337/big_box/40001.txt | 0 .../models/object/1337/boxes.txd | Bin .../models/object/1337/boxes.txt | 0 .../models/object/1337/small_box/40002.col | Bin .../models/object/1337/small_box/40002.dff | Bin .../models/object/1337/small_box/40002.txt | 0 .../models/ped/7/-3.dff | Bin .../models/ped/7/-3.txd | Bin .../models/ped/7/-4.dff | Bin .../models/ped/7/-4.txd | Bin .../models/ped/7/Mafioso 1/-2.dff | Bin .../models/ped/7/Mafioso 1/-2.txd | Bin .../models/vehicle/462/-420.dff | Bin .../models/vehicle/462/-420.txd | Bin .../models/vehicle/490/-1.dff | Bin .../models/vehicle/490/-1.txd | Bin .../vehicle/507/Schafter/-5.dff.nandocrypt | Bin .../vehicle/507/Schafter/-5.txd.nandocrypt | Bin .../models/vehicle/520/-69.dff | Bin .../models/vehicle/520/-69.txd | Bin .../scripts/core/client_logic.lua | 8 +-- .../scripts/core/server_logic.lua | 6 +- .../scripts/core/shared_exported.lua | 6 +- .../scripts/core/shared_importfunc.lua | 0 .../scripts/core/shared_local.lua | 4 +- .../scripts/optional/README.md | 0 .../scripts/optional/alternative/mod_list.lua | 63 ++++++++++++++++++ .../scripts/optional/debug/c_debug.lua | 2 +- .../scripts/optional/debug/g_debug.lua | 0 .../scripts/optional/debug/s_debug.lua | 0 .../optional/nando_crypt/nando_decrypter | Bin .../update_checker/s_update_checker.lua | 0 46 files changed, 124 insertions(+), 41 deletions(-) create mode 100644 .github/doc/MIGRATION.md rename {newmodels_azul => newmodels_red}/meta.xml (97%) rename {newmodels_azul => newmodels_red}/models/README.md (94%) rename {newmodels_azul => newmodels_red}/models/object/1337/SAMP/.gitignore (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/SAMP/README.md (65%) rename {newmodels_azul => newmodels_red}/models/object/1337/SAMP/sampobj.png (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/big_box/40001.col (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/big_box/40001.dff (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/big_box/40001.txt (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/boxes.txd (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/boxes.txt (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/small_box/40002.col (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/small_box/40002.dff (100%) rename {newmodels_azul => newmodels_red}/models/object/1337/small_box/40002.txt (100%) rename {newmodels_azul => newmodels_red}/models/ped/7/-3.dff (100%) rename {newmodels_azul => newmodels_red}/models/ped/7/-3.txd (100%) rename {newmodels_azul => newmodels_red}/models/ped/7/-4.dff (100%) rename {newmodels_azul => newmodels_red}/models/ped/7/-4.txd (100%) rename {newmodels_azul => newmodels_red}/models/ped/7/Mafioso 1/-2.dff (100%) rename {newmodels_azul => newmodels_red}/models/ped/7/Mafioso 1/-2.txd (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/462/-420.dff (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/462/-420.txd (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/490/-1.dff (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/490/-1.txd (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/507/Schafter/-5.dff.nandocrypt (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/507/Schafter/-5.txd.nandocrypt (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/520/-69.dff (100%) rename {newmodels_azul => newmodels_red}/models/vehicle/520/-69.txd (100%) rename {newmodels_azul => newmodels_red}/scripts/core/client_logic.lua (97%) rename {newmodels_azul => newmodels_red}/scripts/core/server_logic.lua (97%) rename {newmodels_azul => newmodels_red}/scripts/core/shared_exported.lua (98%) rename {newmodels_azul => newmodels_red}/scripts/core/shared_importfunc.lua (100%) rename {newmodels_azul => newmodels_red}/scripts/core/shared_local.lua (93%) rename {newmodels_azul => newmodels_red}/scripts/optional/README.md (100%) create mode 100644 newmodels_red/scripts/optional/alternative/mod_list.lua rename {newmodels_azul => newmodels_red}/scripts/optional/debug/c_debug.lua (96%) rename {newmodels_azul => newmodels_red}/scripts/optional/debug/g_debug.lua (100%) rename {newmodels_azul => newmodels_red}/scripts/optional/debug/s_debug.lua (100%) rename {newmodels_azul => newmodels_red}/scripts/optional/nando_crypt/nando_decrypter (100%) rename {newmodels_azul => newmodels_red}/scripts/optional/update_checker/s_update_checker.lua (100%) diff --git a/.github/doc/DOCUMENTATION.md b/.github/doc/DOCUMENTATION.md index ce50ffc..6b3ff9e 100644 --- a/.github/doc/DOCUMENTATION.md +++ b/.github/doc/DOCUMENTATION.md @@ -1,4 +1,4 @@ -# `Newmodels v5 Azul ๐Ÿ’™` Documentation +# `Newmodels v6 Red ๐ŸŸฅ` Documentation ## Requirements @@ -19,18 +19,18 @@ |--------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **What do I need to know to use this system?** | Basic knowledge of MTA scripting (Lua) and how MTA servers and game clients work. | | **Who is this system intended for?** | Server owners and developers who want to add new models to their MTA server for custom skins, vehicles, objects, etc. | -| **Will players download the files (DFF/TXD/COL) of the added models automatically?** | Yes, the [`meta.xml`](/newmodels_azul/meta.xml) configuration includes all of these files in the [models folder](/newmodels_azul/models/) so they are automatically downloaded by players when they join the server. | +| **Will players download the files (DFF/TXD/COL) of the added models automatically?** | Yes, the [`meta.xml`](/newmodels_red/meta.xml) configuration includes all of these files in the [models folder](/newmodels_red/models/) so they are automatically downloaded by players when they join the server. | | **Why not use the `download="false"` attribute in the `meta.xml` so they are not downloaded by players, then download them on demand?** | This feature is currently not implemented due to common complaints about `downloadFile` sometimes being unreliable and causing server lag. It is better to serve all files to the player at once. | | **Can I encrypt my model files and hide the decryption key so players cannot steal them?** | Yes, you can use the **NandoCrypt** which is natively supported by this system. | | **How are added models identified?** | New models are identified by numerical IDs that you define. These IDs can be any number (positive or negative) as long as they do not conflict with existing or reserved game IDs. They are purely arbitrary and do not have to be sequential. | | **Why new model IDs and not strings/names for identification?** | MTA uses numerical IDs to identify models, so this system follows the same convention. It is more efficient and easier to work with numbers than strings. | -| **How do I add models using this system?** | Essentially, you add new models by placing the DFF/TXD/COL files in the [models folder](/newmodels_azul/models/) with specific file and folder names. | +| **How do I add models using this system?** | Essentially, you add new models by placing the DFF/TXD/COL files in the [models folder](/newmodels_red/models/) with specific file and folder names. | | **How do I use the new models in my scripts?** | You can use the exported functions provided by this system in your own scripts. | | **Can I use the new models in my existing scripts without modifying them?** | In theory, yes. You can use the `loadstring` method to import the functions at the beginning of your script. This will modify the MTA functions to work with the new IDs. However, always be careful and verify if you do not break any feature in your scripts. | | **Can I use the new models in my existing scripts by calling the exported functions directly?** | Yes, you can call the exported functions directly in your scripts, without using `loadstring`. | | **Can I use the new models in both server-side and client-side scripts?** | Yes, the exported functions are shared, meaning you can use them in both client and server side scripts. However, their behaviors are different. | | **Why is are new models added client-side in MTA and this logic doesn't exist server-side?** | MTA model allocation happens client-side, so the server has no concept of any new IDs. Server-side model allocation is still not implemented on MTA (but may be in the future ๐Ÿ˜‰), so this system provides a way to work around this limitation. | -| **Are there any premade modpacks for new models that I can drag & drop to my server?** | Sure, the community has created many new object, vehicle and skin mods over the years. You can search for these models online. [You can find more information here about adding all of SA-MP's objects.](/newmodels_azul/models/object/1337/SAMP/README.md) | +| **Are there any premade modpacks for new models that I can drag & drop to my server?** | Sure, the community has created many new object, vehicle and skin mods over the years. You can search for these models online. [You can find more information here about adding all of SA-MP's objects.](/newmodels_red/models/object/1337/SAMP/README.md) | ## Basics @@ -51,7 +51,7 @@ A game model can be added with up to **3 different files** for a certain entity - `vehicle`: DFF and TXD files - `object`: DFF, COL and TXD files -The files must be placed in the [models](/newmodels_azul/models/) folder. The system will automatically load them. +The files must be placed in the [models](/newmodels_red/models/) folder. The system will automatically load them. #### File & Folder Structure @@ -67,13 +67,13 @@ e.g. `models/ped/7/Mafioso 1/-2.dff` #### NandoCrypt Support (Optional) -You may use [NandoCrypt](https://github.com/Fernando-A-Rocha/mta-nandocrypt) to encrypt your mod files. Place them with file extension `.nandocrypt` so they are automatically recognised. You may customize the file extension in [`shared_local.lua`](/newmodels_azul/scripts/core/shared_local.lua). +You may use [NandoCrypt](https://github.com/Fernando-A-Rocha/mta-nandocrypt) to encrypt your mod files. Place them with file extension `.nandocrypt` so they are automatically recognised. You may customize the file extension in [`shared_local.lua`](/newmodels_red/scripts/core/shared_local.lua). A test `nando_decrypter` script is included with the resource, as well as a mod consisting of 2 encrypted files (`-5.dff.nandocrypt` and `-5.txd.nandocrypt`). To use your own mods, you will have to replace `nando_decrypter` with your own decrypter script generated by the NandoCrypt tool. #### Additional customization -Models can be customized with `.txt` files. Check [this README](/newmodels_azul/models/README.md) for more information. +Models can be customized with `.txt` files. Check [this README](/newmodels_red/models/README.md) for more information. ### 2. Using the new models @@ -96,12 +96,12 @@ In contrast, **client-side** functions do not perform any synchronization of dat The easiest way is to use the following method in the beginning of your script to load the necessary functions. ```lua -loadstring( exports['newmodels_azul']:import() )() +loadstring( exports['newmodels_red']:import() )() ``` This modifies MTA functions such as `createVehicle` or `setElementModel` to work with the new IDs, and adds new functions such as `getElementBaseModel` and `getElementCustomModel` that you can use. -Check the [`shared_exported.lua`](/newmodels_azul/core/shared_exported.lua) script to know what gets imported. +Check the [`shared_exported.lua`](/newmodels_red/core/shared_exported.lua) script to know what gets imported. Example usage: @@ -114,14 +114,14 @@ local vehicle = createVehicle(id, x, y, z, rx, ry, rz, numberplate) If you do not wish to use `loadstring` to import the functions, you can call them directly. -Check the [`meta.xml`](/newmodels_azul/meta.xml) file to see the exported functions. +Check the [`meta.xml`](/newmodels_red/meta.xml) file to see the exported functions. Example usage: ```lua -- The normal createVehicle would not work with invented IDs such as -2, -- so we call the available exported function -local vehicle = exports['newmodels_azul']:createVehicle(id, x, y, z, rx, ry, rz, numberplate) +local vehicle = exports['newmodels_red']:createVehicle(id, x, y, z, rx, ry, rz, numberplate) ``` ### Important Tips โš ๏ธ diff --git a/.github/doc/MIGRATION.md b/.github/doc/MIGRATION.md new file mode 100644 index 0000000..09bd10a --- /dev/null +++ b/.github/doc/MIGRATION.md @@ -0,0 +1,14 @@ +# Migrating from previous `Newmodels` versions + +This article explains how to migrate from previous versions of newmodels to the newest `Newmodels v6 Red ๐ŸŸฅ` version. + +## Migrating from v4 and v5 + +You just need to migrate your model files (dff, txd, col, etc.) to the new `newmodels_red` resource! They will load and work as before. + +## Migrating from v3 + +Migrating from newmodels v3 is now possible, as the system has now evolved with backwards compatibility in mind. However, some breaking changes have been introduced in v6 that you should be aware of. + +todo + diff --git a/README.md b/README.md index 847ea01..b40a6fc 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# `Newmodels v5 Azul ๐Ÿ’™` +# `Newmodels v6 Red ๐ŸŸฅ` This MTA resource makes use of the clientside allocated models ([engineRequestModel](https://wiki.multitheftauto.com/wiki/EngineRequestModel) and related features) to add new peds (skins), vehicles and objects: @@ -21,7 +21,13 @@ Get the [Latest Version](https://github.com/Fernando-A-Rocha/mta-add-models/rele ## Older versions -It is easy to migrate to v5 from newmodels v4 (not from v3; the architecture of that version is no longer used). The **models folder structure remains the same**, but the scripts have changed in the way models are applied to elements. +It is easy to migrate to v6 from **newmodels v4 and v5**. The **models folder structure remains the same**, but the scripts have changed in the way models are applied to elements. + +Migrating from **newmodels v3** is special because the architecture of that version was different. + +Please refer to the [Migration Guide](/.github/doc/MIGRATION.md) for more details. + +### Important changes This resource no longer uses and relies on the **MTA Element Data system** (`setElementData`) to sync the models to all clients! Instead, newmodels makes use of Lua tables and MTA events. This major change was made to **improve performance** and control the sync of models more efficiently. diff --git a/[examples]/test_vehicles/meta.xml b/[examples]/test_vehicles/meta.xml index 8bbf630..aa19967 100644 --- a/[examples]/test_vehicles/meta.xml +++ b/[examples]/test_vehicles/meta.xml @@ -1,5 +1,5 @@ - +