search

cyberrumor / ammo

Almost Manual Mod Organizer - Linux MO for Bethesda Games
GNU General Public License v2.0
25 stars 6 forks source link

Documentation needs improvement #35

Closed ignazkrum closed 7 months ago

ignazkrum commented 9 months ago

Hey, just noticed that the documentation is a little lacking, at least for me. Frankly, i'm not sure where to begin, but I'll list off some issues I've had over the past hour or so.

  1. First off, I can't quite figure out how exactly to download and install mods. I assume that the ~/Downloads folder cited in the help menu is the basic system's download folder, but nothing showed up in the Index | Download section aside from a preexisting SKSE install until after I ran install all , at which point SKSE seems to have been duplicated to the "mod name" section of the UI, and the other two mods appeared in the downloads section
  2. So, to take rename (mod|download) <index> <name> . The (mod|download) section confuses me. Does this mean the name of the mod in the download section? And the index # in the download section? Or does it mean that the mod could be in the mod or download section?
  3. The index numbers of the various mods seem to be independent of each other depending on which section you look at. Is this intended? Do they all mean something? how do I know which ones to use?

  4. so, here I'm trying to rename SKSE.

    
index | Download
-------|---------
[0]     SkyUI_5_1-3863-5-1.7z
[1]     A Quality World Map 9.0.1 - Vivid with Stone Roads-4929-9-0-1.zip
[2]     skse_1_07_03.7z

index | Activated | Mod name
-------|-----------|------------
[0]     [False]     skse_1_07_03

index | Activated | Plugin name
-------|-----------|------------

Skyrim >_: rename skse_1_07_03.7z 2 SKSE arg was unexpected type: 'SKSE_1_07_03.7Z' [Enter]


what does that error message mean? Are 7z files not valid? You may see several of the above issues being shown here.
5. This is a more general one, but I'm unclear exactly what the organizer does and how to use it. Do I run skyrim through Steam? If so, using the Skyrim or SKSE library entries? Can AMMO use Bodyslide, LOOT, FNIS, Wrye Bash, or other common mod Organizer utilities? If so, how do i do it? There's a lot missing from the documentation, and I'm sure I'll run into more problems if there isn't a start-to-finish user's guide or something of the sort.
6. in the Dependencies section, it does not include Git, which is definitely a dependency.
7. I am unclear how exactly the modlist UI works, and why SKSE is not listed as a plugin, despite being one as far as my memory of MO2 is concerned.
8. [edit] Does AMMO use my system downloads folder as some kind of install folder? I didn't put SkyUI or the map mod anywhere else.
9. Having installed and activated the three mods, suddenly the DLCs have appeared in the plugin section, seemingly inactivated, with a higher load index # than the other two mods in that section. I have no idea what this is, they weren't there before.

That's all I can think of for now, but I would personally recommend reaching out about the project to youtubers in the linux/gaming space, for the sake of potential new contributors to make general development easier. I get that most of us don't have a lot of time for this kind of thing, which is why getting the word out is so important (I for one only found this project from your reddit comment 10 months ago). I'm sure you have some ideas on who you could send this project to, but that's ultimately up to you.

Thank you very much for this project, and Sorry if i don't respond to questions/comments quickly, I don't usually check messages.
cyberrumor commented 9 months ago

Hey mate, thanks for the write up, that's valuable feedback. I'll answer your questions and have a think about improving docs. I might make a video at some point just to reduce the barrier of entry.

First and foremost, the help menu is standard POSIX / docopt style syntax. The syntax basically breaks down like this:

It's also worth noting that each list has independent indexes (mods, plugins, downloads).

Armed with that information, I'll show you some examples of the help menu and some things you could actually type based on that syntax.

I hope that helps with the syntax. Now, to address your numbered points:

  1. This sounds like you downloaded skse, opened up ammo, then downloaded the other mods. Ammo doesn't update your downloads list live, you have to issue refresh. When you ran install all, ammo still wasn't aware that there were new files in your downloads folder, so it only installed the one it could see: skse. Once it was done installing, it refreshed automatically (it does this after operations that require an absence of uncommitted changes to run, like install), and finally displayed your new downloads. Skse wasn't duplicated from downloads to mods, it was extracted from downloads to mods. If you're done with the archive in downloads, you can delete it with delete download 2 (index might be different if you have more downloads since the state you pasted above, just use the number to the left of skse_1_07_03.7z.
  2. Touched on this a bit above, but you replace <index> with the literal number that is to the left of the component you want to match. If the command you're using expects a type of component (like (mod|download)), the index that is matched is the index from that particular type of component's list.
  3. Same as above. I think the point you got caught up on is that you were expecting to type the mod or download name instead of the numbers associated with them.
  4. The error message means the rename command expected an integer (denoted by <index> in the help menu) but received a string with the text shown in the error instead. Correct syntax to do what you want would be one of these:
    • rename download 2 SKSE: renames the download named skse_1_07_03.7z to SKSE.7z
    • rename mod 0 SKSE: renames the mod named skse_1_07_3 to SKSE
  5. Ammo organizes your mods. Essentially, it will make it easy for you (compared to manual, or in my biased opinion, mucking about with installing windows-based mod organizers into your prefix) to install, uninstall, reorder, and sort mods and plugins. That's it. It doesn't hook into external tools like MO2 does, but that doesn't mean you can't use them. You'll launch the game through Steam (ammo is a mod organizer, not a game launcher or external tool aggregator). To make steam launch skse when you hit play, you'll want to manually make a backup of SkyrimSELauncher.exe and manually copy your skse_loader.exe to SkyrimSELauncher.exe. You'll do this after you install skse with ammo. If you need to uninstall skse, uninstall it through ammo, then manually rename SkyrimSELauncher.exe.bak (or whatever you named your backup) to SkyrimSELauncher.exe. Since there's no external tool integration, you'll probably want to make your own helper scripts for things like xEdit and whatever else you use. I personally don't use LOOT and I haven't looked into using it outside of a mod organizer. It's probably possible but you'd likely need to write some code. Anyway, I have some scripts that I keep in /usr/local/bin to launch external tools through wine, using the game prefix. You'll need to run chmod +x <script name> on them. Here's some examples:

/usr/local/bin/bethini

#!/bin/bash
WINEPREFIX=$HOME/.steam/steam/steamapps/compatdata/489830/pfx wine $HOME/.steam/steam/steamapps/common/Skyrim\ Special\ Edition/Data/BethINI.exe

/usr/local/bin/bethkit

#!/bin/bash
WINEPREFIX=$HOME/.steam/steam/steamapps/compatdata/489830/pfx wine $HOME/.steam/steam/steamapps/common/Skyrim\ Special\ Edition/Data/bethkit.exe $@

/usr/local/bin/sseedit

#!/bin/bash
WINEPREFIX=$HOME/.steam/steam/steamapps/compatdata/489830/pfx wine $HOME/.steam/steam/steamapps/common/Skyrim\ Special\ Edition/SSEEdit.exe -I:$HOME/.steam/steam/steamapps/compatdata/489830/pfx/drive_c/users/steamuser/Documents/My\ Games/Skyrim\ Special\ Edition/Skyrim.ini

/usr/local/bin/sselodgen

#!/bin/bash
WINEPREFIX=$HOME/.steam/steam/steamapps/compatdata/489830/pfx wine $HOME/.steam/steam/steamapps/common/Skyrim\ Special\ Edition/SSELODGen.exe -sse -o"$HOME/Downloads/output" -I:$HOME/.steam/steam/steamapps/compatdata/489830/pfx/drive_c/users/steamuser/Documents/My\ Games/Skyrim\ Special\ Edition/Skyrim.ini

and so on and so forth. Note that these examples assume you've installed the associated tool through via ammo. You'd then run sselodgen from terminal, or bethkit, or whatever you named the script.

You won't really find a start to finish guide for this tool, considering the limited scope. But I will say that since I don't have an overwrite folder (like MO2), the closest equivalent ammo supports is basically this workflow:

As you can see, it's possible to use external tools, but there's no integration. Since every tool is different, you'll sort of have to understand how those tools work and how ammo works to figure out how to use them alongside each other. For tools that put files in your game folder, the above workflow should be pretty ubiquitous :)

  1. It's a dependency to download it, but not to build it or install it. Every repository on github would be saying git is a dependency if download dependencies were included, but they don't, so I don't.

  2. The UI will reflect the in-memory state of ammo. The indexes you can select for each category of component (mod, plugin, download) are listed on the left, names on the right. The index indicates your load order. Higher numbers win file conflicts. Obviously the load order of downloads don't matter, but using the index instead of the name for commands makes it so you don't have to type out long mod names every time you want to make a change. If there's a warning after executing a command (or attempting to execute a command and not being able to due to incorrect args for example), the warning will be displayed and you will have to hit your return key before the UI will accept input again. If you have an *>: prompt, it means you have unsaved changes and you need to run commit before you exit ammo or your changes won't be saved. It also means some commands can't be used since they require an absence of unsaved changes to execute. If you've downloaded mods or executed commands that you don't want to persist since the last time you ran commit, you can reload config from disk with refresh. Note that commands that require an absence of pending changes will commit changes instantly. They do this to prevent the possibility of a user having broken symlinks if they exit ammo before running commit, hence requiring an absence of changes.

SKSE doesn't have a plugin when it's enabled because there's no esp for skse. Mods with plugins will show plugins in ammo only when that mod is enabled.

  1. Ammo uses $HOME/Downloads for your downloads folder, $HOME/.local/share/ammo//mods for your mods folder, $HOME/.local/share/ammo//ammo.conf for your mod load order, and ~/.local/share/Steam/steamapps/compatdata/489830/pfx/drive_c/users/steamuser/AppData/Local/Skyrim\ Special\ Edition/Plugins.txt for your plugin load order.

  2. Sounds like a bug. I haven't seen my DLC show up in quite some time (but it still loads) likely due to nothing creating a DLCList.txt in the same location Plugins.txt is stored. Are you experimenting with other mod organizers alongside this? If so, one of them may have created DLCList.txt which caused the plugins to appear in ammo. If you're not, that sounds like a bug and I'll look into it.

Anyway thanks for the feedback, I'll probably make a video tutorial or something, which would likely be the most concise way to teach people how to use it. Let me know if you have more questions :)

ignazkrum commented 9 months ago

Thanks very much for the reply, that info on syntax and command rules in particular is very helpful.

  1. This might be outside the scope of the documentation, but what is a FOMOD? I was under the impression that fomods were something like the GUI installer wizards that many of the larger/more complex mods would use to enable the user to have configuration options with regards to what parts/patches of a mod to install. I don't think SkyUI works like that, correct my if i'm mistaken.
  2. What would be some good "software hygiene" procedures to follow when using AMMO? MO2 uses it's own virtual folders to prevent mucking things up in game files, but it seems like many of the ways AMMO functions (in particular in regards to external tools) would need a bit more caution than I'm used to. I run a pretty low-grade system (intel iGPU, 8gb ram), and we all know how janky and unstable Bethesda's games can be at the best of times, let alone with my amateurish modding attempts.
  3. I'm playing LE, and SKSE has always seemed to function fine without any work on my part. It adds a new entry called "SKSE" into the steam library, though the behavior seems to have changed noticeably on linux for whatever reason, both skyrim and SKSE loading up the modded game, and both with the "title window" of maybe 400x600pixels prior to the main menu screen which was only present on the unmodded steam entry while using windows (odd, but whatever). Do i still need to do the SKSE setup you provided in section 5.?
  4. Is there any way to view more information on mods through AMMO? I'm considering editing the names of the mods to shorter, more succinct forms without things like version numbers, but I'm worried about losing track of these if I do that.
  5. I can't quite find the scripts. I've checked [disk]/usr/local/bin But nothing seems to be relevant, there are a few executables and no child folders. In [disk]/home/[my username]/.local/bin there are again a few executables, but only one is related to AMMO, and it's this one 
    
#!/usr/bin/python3
from ammo.game_controller import GameController
from ammo.ui import UI

controller = GameController() ui = UI(controller) ui.repl()


6. In response to 9., i did have Mod Organizer installed prior to trying out AMMO, but reinstalled the game on Steam to allow for a fresh slate (the method I found had done some edits to the game files IIRC) and haven't booted it up since. It does seem to be a bug, though i don't recall for sure which command i entered just prior to the DLC files showing up (might have been activate?). It does seem like a bug. Should there be any effect to leaving them active/inactive? Or will they show up in my game as usual if I just leave them inactive.

Thanks again for answering my questions.
cyberrumor commented 9 months ago

Happy to help. I'm actually working on putting a wiki together today that will take you through everything that I know how to do step by step.

  1. You're correct, FOMOD is technically a specification, but I've taken to calling mods that require configuration via a wizard compatible with the spec a FOMOD. My memory thought skyUI was a fomod, but it's possible I'm mistaken.
  2. Good software hygiene for modding with ammo:
    • Only use one mod organizer per game install location (E.g. you can use ammo with skyrim steam and MO2 with skyrim flatpak steam, and it will be fine. But don't use ammo and MO2 together on the same instance of your game).
    • Ammo considers symlinks in the game directory as "owned". It will delete them even if it didn't create them. If you need a file to persist in the game directory, either put that file in a mod and activate the mod, or leave that file in the game directory as a normal file (not a symlink).
    • The way ammo resolves conflicts is functionally the same as MO2, but since we're on linux, we get to use symlinks instead of a virtual filesystem to achieve the same effect.
    • If you need to return to vanilla, just deactivate mod all then commit and you're done (don't forget to manually restore your SkyrimLauncher.exe.bak if you made one from the script extender install instructions).
    • If possible, point your modding tools that generate output at a folder ~/.local/share/ammo/Skyrim/mods/overwrite so they don't pollute your actual game directory with non-symlink files. This will allow ammo to easily manage the output of tools.
    • You should really try Skyrim SE, it's a lot less crash-prone than LE, and it doesn't have Z-fighting or shadow striping. It's also able to use more than 4g of ram.
    • It's faster to make a small number of changes between testing your game than it is to make a large number of changes before testing, finding something is broken, then spending hours trying to determine what broke it.
  3. Instructions for getting skse up and running are in the wiki now. I would highly recommend installing skse as described there instead of via whatever method you were using before. I'm not sure what you're talking about with the new skse entry.
  4. Renaming a mod with ammo is safe. It essentially just executes this: mv ~/.local/share/ammo/Skyrim/mods/old_mod_name ~/.local/share/ammo/Skyrim/mods/new_mod_name and rebuilds the symlinks. As far as viewing more information, not yet. I was considering adding something like a conflicts command that would show which mods have files that other mods also have. You can always hop into your ~/.local/share/ammo/Skyrim/mods and create and destroy files there, just make sure you restart ammo and run commit if you do that, otherwise you'll have broken symlinks.

If you specifically mean "more data" as in "metadata from nexusmods", there's not and won't be. This goes back to the scope of ammo being a mod organizer and not something else (like a nexusmods client).

  1. You'll have to make the scripts, they don't exist by default. There's a few examples in the wiki. See the xlodgen one in particular.
  2. I'll keep my eye on that. If you're able to find a reliable way to reproduce it, open an issue explaining how you did it and I'll get it sorted.

EDIT:

Forgot to address your point on the DLC. If you can see your DLC, you should be able to enable / disable / reorder the plugins like you would with any other plugin. Since they're not associated with a mod, there's nothing to delete for them (can only delete mods and downloads, not plugins).

cyberrumor commented 9 months ago

Also I've been playing around with Skyrim LE and can confirm ammo was way broken with it. Please update ammo, it should be working now.

ignazkrum commented 9 months ago

Also I've been playing around with Skyrim LE and can confirm ammo was way broken with it. Please update ammo, it should be working now.

will do

[Edit] This is probably a stupid question, but how do I update it?

cyberrumor commented 9 months ago

You have to cd into the directory you cloned it from then run git pull. That will download the update. Then run

pip3 install --force-reinstall . || pip3 install --break-system-packages --force-reinstall .

then fully exit ammo if it was running.

cyberrumor commented 7 months ago

I'm closing this due to inactivity, if you have further questions or specific recommendations for wiki enhancements, feel free to open another issue. Thanks!