Makefile image download automation + markdown revisions (sirgwain#581)

* Makefile fixes

* Update Makefile

* Moved FAQ to new file; markdown revisions

* fixed images, updated makefile

* fixed tpyo

* Update faq.md

---------

Co-authored-by: sirgwain <[email protected]>

Makefile

@@ -13,14 +13,17 @@ BINARY_NAME := craig-stars.exe
 mkdir = if ( -not ( Test-Path $(1) ) ) { mkdir "$(1)" }
 rm = if ( Test-Path $(1) ) { rm -Recurse -Force "$(1)" }
 cp = Copy-Item -Path "$(1)" -Destination "$(2)" -Force
-
+download = Invoke-WebRequest -Uri "$(1)" -OutFile "$(2)"
+unzip = Expand-Archive -LiteralPath "$(1)" -DestinationPath "./"
 else
 # Unix commands
 BUILDTIME := $$(date +'%y.%m.%d %H:%M:%S')
 BINARY_NAME := craig-stars
 mkdir = mkdir -p $(1)
 rm = rm -rf $(1)
 cp = cp $(1) $(2)
+download = curl -q $(1) -o $(2)
+unzip = unzip $(1)
 endif
 
 # replaces backslashes with unix-style frontslashes 
@@ -37,10 +40,18 @@ build_thing := go build \
 	main.go
 
 # always redo these
-.PHONY: run build test clean dev dev_backend dev_frontend
+.PHONY: run images build test clean dev dev_backend dev_frontend
 
+# clean, deploy and launch all in 1 command
 run: clean build dev 
-
+
+images:
+	cd frontend/static;\
+	$(call rm,./images);\
+	$(call download,https://craig-stars.net/images/images.zip,images.zip);\
+	$(call unzip,images.zip);\
+	$(call rm,images.zip)
+
 build: build_frontend tidy vendor generate build_wasm build_server
 
 build_frontend:

docs/architecture.md

@@ -24,13 +24,9 @@ Every entity in a `craig-stars` game has an integer `Num` associated with it. `N
 
 ### Specs
 
-`craig-stars` has a lot of computed values. Planets compute their habitability and growth, ship designs compute their power rating, fleet's compute their cargo capacity and fuel capacity. All computed values are stored in an object's `Spec` field, and are computed by the various `compute*Spec` functions. Specs are computed at the start and end of turns (and sometimes during turns). When players update orders, specs are also recomputed. The spec calculations use the Game's Rules for their various constants.
+`craig-stars` has a lot of computed values. Planets compute their habitability and growth rate, ship designs compute their power rating and component bonuses, fleets compute their cargo/fuel capacity, etc. All computed values are stored in an object's `Spec` field, and are computed by the various `compute*Spec` functions. Specs are computed at the start and end of turns (and sometimes during turns where needed). When players update orders, specs are also recomputed. Spec calculations relying on preset constants reference the Game's `Rules` struct to access said constants.
 
-An example of a `Spec` calculation is the maximum usable factories for a planet, that is dependent on planet population and the race number of factories value.
-
-```go
-spec.MaxFactories = planet.population() * race.NumFactories / 10000
-```
+One such dynamically computed `Spec` value is the maximum usable factories for a given planet, dependent on its population/max population and the race's preset "factories operated" value.
 
 ### Entity Diagram
 

docs/development.md

@@ -30,43 +30,46 @@ From there, you can install `make` and `node.js` (which includes npm) fairly eas
 
 If you're on Windows, *make sure to have Powershell installed and in your PATH* for the makefile to function correctly. In 99% of cases, this shouldn't be an issue (powershell is bundled with all currently supported Windows versions to date and has been the default shell since Windows 10), but if your machine somehow doesn't have it, use winget in command prompt (`winget install --id Microsoft.PowerShell --source winget`) to install the latest version. (On Mac/Linux, any terminal should be fine as long as it supports the `mkdir`, `rm`, `cp` and `date` instructions.)
 
-### GCC
+## GCC
 Additionally, the [go-sqlite3](https://github.com/mattn/go-sqlite3) package `craig-stars` relies on for databasing itself requires the [GNU compiler collection](https://gcc.gnu.org/) to run. You **will** need GCC installed and built to run `craig-stars` locally!
 
 On Linux/Mac, you can simply download the latest version of the GCC compilers using whatever package software you installed previously and build it from there. However, on Windows, you'll need to install a Linux-like development interface (use [MinGW64](https://www.mingw-w64.org/) - Cygwin64 has been known to cause issues) to install/build the latest GCC version due to file type restrictions.
 
 ## Assets
-You will need art assets for ships and such, and those can be downloaded from [https://craig-stars.net/images/images.zip](https://craig-stars.net/images/images.zip). Copy these images into the `frontend/static/images` folder (or make a new folder if it doesn't already exist).
+You will need art assets for ships and planets - otherwise they'll just look like black boxes.Thankfully, you can now download the images with a single makefile command! (Since the image files are stored on the cloud, this requires an internet connection.) 
+```bash
+make images
+```
+The command will clear out the previous images folder before downloading and extracting `images.zip` (https://craig-stars.net/images/images.zip) into `frontend/static/images`
+
+**You only ever need to download the image files once.** 
+Of course, if any new items or icons come along that need to be downloaded, you'll need to update it with the new files if you want to see them in local host. 
 
 ## Installing Air
 [Air](https://github.com/air-verse/air) is a Go utility that aids in automatic server restarting. While modifying the frontend code will trigger a hot reload of the local program (allowing for immediate confirmation of changes in real time), changes to the `golang` backend are only reflected the _next_ time the program is launched (requiring you to kill and restart the program each time). `Air` helps automate this "kill and restart" process by shutting down and reloading the server every time changes are detected. 
 
-Installing air is **not required** to run craig-stars locally, but can be helpful if you plan on frequently making changes to the backend and want real time confirmation.
+Installing air is **not required** to run craig-stars locally, but can be helpful if you plan on making frequent backup changes and want both real time confirmation and maximum laziness.
 
 To install air, enter the following code into your terminal:
 ```bash
 go install github.com/air-verse/air@latest
 ```
 
 ## Building and Running
-After performing all that, go to your terminal and enter the following commands:
+After performing all that, go to your terminal and enter the following command:
 
 ```bash
-make build
-make dev
+make run
 ```
 
 **Note** On first launch, this will create an empty database with a single `admin` user, password `admin`.
 
-If done correctly, it should give a localhost link (http://localhost:5173/) representing the application being hosted locally on your machine. Go to that site to see a live reloading frontend proxied to the go server on port `:8080`. Updating go code will re-launch the backend automatically (via air), while updating frontend code will do a hot reload with sveltekit/vite.
-
-# Visual Studio Code 
-[VS Code](https://code.visualstudio.com) is highly recommended for development. `craig-stars` comes with a [cs.code-workspace](/cs.code-workspace) file that can be opened with VS Code in order to use frontend and backend plugins without issue in the same repo. It also comes with a built in terminal, debugging support, and an array of assorted bells and whistles useful for general software development.
+If done correctly, it should give a localhost link (http://localhost:5173/) representing the application being hosted locally on your machine. Go to that site to see a live reloading frontend proxied to the go server on port `:8080`. Updating Go code (backend) will re-launch the backend automatically (via air), while updating Svelte or Typescript code (frontend) will perform a hot reload with sveltekit/vite.
 
-## backend
-To launch the backend separately from the frontend, you can call `air` directly (or equivalently, run the `dev_backend` makefile recipe). 
+### Backend/Frontend only
+To launch the backend separately from the frontend, you can call `air` directly (or equivalently, run the `dev_backend` makefile recipe which does just that). 
 
-```zsh
+```bash
 ❯ air
 
   __    _   ___
@@ -91,35 +94,21 @@ running...
 7:47AM DBG Debug logging enabled
 ```
 
-## frontend
-Launch the frontend in development mode with npm:
+If one wants to exclusively launch the frontend, it can be run in development mode with npm:
 
-```zsh
-cd frontend
-npm run dev
+```bash
+make dev_frontend
 ```
 
-## test
-Run tests:
+# Visual Studio Code 
+[VS Code](https://code.visualstudio.com) is highly recommended for development. `craig-stars` comes with a [cs.code-workspace](/cs.code-workspace) file that can be opened with VS Code in order to use frontend and backend plugins without issue in the same repo. It also comes with a built in terminal, debugging support, and an array of assorted bells and whistles useful for general software development.
 
-```zsh
-make test
-```
+## Testing
+While manual local dev testing is good, software testing & debugging are also crucial to ensure things run (and continue to run) smoothly. After writing new or updating existing tests, there are several options as for how to run them:
+* Run `make test` to run all the tests at once (great for overall checks to make sure everything works, bad for specific debugging)
+* Run tests via command line (`go test` and `npm run test` for frontend/backend respectively, followed by the specific test file name(s) for specific coverage)
+* Run/debug using the Testing panel in the activity bar - tests can be filtered by result, directory, etc. 
+* Run/debug using the small buttons displayed in test files and next to test functions.
 
 # Troubleshooting
-"I try to click on the login button on localhost using the admin credentials and it does nothing! Also, an error pops up in my terminal!"
-
-You probably aren't running the backend. Open a new terminal tab and type `air` to build the backend needed to handle all the nitty gritty logic stuff.
-
-"When I run air, my computer complains about undefined Sqlite Drivers!"
-
-See [Getting started](#Getting Started).
-
-"When I run make build, I get an obscure error about 'executable not found in %PATH%' or 'build target excluding all files in XXX'!"
-What's probably happening is you're trying to generate go files or build the server with the incorrect GOARCH and GOOS settings. Try using `go env -u GOOS GOARCH` to reset them to their defaults and see if the problems persist.
-
-"I tried to do all of the above, but I'm still getting errors in the command line!"
-Consult this ordered checklist of vague general suggestions:
-1. Read the error message to try and figure out why it's failing. Make (as it's being used here) effectively just copy-pastes its commands into the terminal one by one (expanding variables here and there), so syntax errors in the terminal can oftentimes reflect issues with the makefile itself rather than any device-related issues. 
-2. Try and search online for the error message or similar problems to see if others may have found solutions to the problem for you. 
-3. If all else fails, reach out in the #stars-clones or #craig-stars channels in the discord (ideally with images/text of the commands used and/or resulting error messages).
+See [Common Problems](faq#common-problems) in the FAQ for solutions to some common local dev issues.

docs/faq.md

@@ -0,0 +1,24 @@
+## Common Problems
+- "I try to click on the login button on localhost using the admin credentials and it does nothing! Worse, an error pops up in my terminal!"
+
+You probably aren't running the backend server. Open a new terminal tab and type `air` to build the backend needed to handle all the nitty gritty logic stuff (including login credentials).
+
+- "When I run air, my computer complains about undefined Sqlite Drivers!"
+
+See the [GCC](#gcc) section for info on how to install `go-sqlite3` and `GCC`.
+
+- "When I run `make build`, I get an obscure error about 'executable not found in %PATH%' or 'build target excluding all files in XXX'!"
+What's probably happening is you're trying to generate go files or build the server with the incorrect GOARCH and GOOS settings. Try running `go env -u GOOS GOARCH` to reset them to their defaults and see if the problems persist.
+
+- "When I boot up the server, all the ships have no icons!"
+See [Assets](#assets) for information on how to download art assets.
+
+- "I tried to run `make images`, but the command failed!`
+in the event `make images` fails, you'll have to extract [the images](https://craig-stars.net/images/images.zip) manually and move the image files to `frontend/static/images` yourself.
+
+- "I'm getting some other errors in the command line!"
+Consult this ordered checklist of vague general suggestions:
+
+1. Read the error message to try and figure out why it's failing. Make (as it's being used here) effectively just copy-pastes its commands into the terminal one by one (expanding variables here and there), so errors in the terminal can be a symptom of bad or incorrect launch commands.
+2. Try and search online for the error message or similar problems to see if others may have found solutions to the problem for you.
+3. If all else fails, reach out in the #stars-clones or #craig-stars channels in the discord (ideally with images/text of the commands used and/or the resulting error messages - vague comments like "AAA MY BUILD IS BORKING" tend to be hard to troubleshoot).