From 7cfd3f707e1a72a922b7ef0fc697a8698f02ffa4 Mon Sep 17 00:00:00 2001 From: Rykka Date: Sat, 16 Apr 2022 22:11:27 -0600 Subject: [PATCH] Adds Multiple Discord-Only Guides to our Repository. Self-Explanatory. Direct newer contributors towards these. These should help with contributors being able to review these publicly. Guide to Contribution and Wiki Pages to follow once the author has time to do so, or alternatively, someone can beat them to it and do it. A good reference for such would be TGMC's Guide to Contributing (Written for very, very new folks, and a gold standard for walkthroughs.) Additionally, this updates the workspace recommendations, to include the following: Auto Comment Blocks Gitlens (For Gitblaming/seeing last-changed inside files) Indent Rainbow (Easier viewing of indents) DarkPurple-Black (Personal Recommendation, Colors the Terminal Errors tab well) ESLint (Support for ESLint Javascript in VSC) Editor Config for VSCode TGStation Test Adapter (Allows you to run Unit Tests, whenever I actually fix these to work locally) Discord Rich Presence (Not Required, but nice to have.) --- .vscode/extensions.json | 14 +- guides/Guide to Your First POI Map.md | 155 ++++++++++++++++++ ...vermap Ships and Places - What's Needed.md | 59 +++++++ guides/VSCode Setup Guide.md | 30 ++++ 4 files changed, 255 insertions(+), 3 deletions(-) create mode 100644 guides/Guide to Your First POI Map.md create mode 100644 guides/Overmap Ships and Places - What's Needed.md create mode 100644 guides/VSCode Setup Guide.md diff --git a/.vscode/extensions.json b/.vscode/extensions.json index 9099488143..19a0ceb7de 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,6 +1,14 @@ { "recommendations": [ - "gbasood.byond-dm-language-support", - "platymuus.dm-langclient" - ] + "gbasood.byond-dm-language-support", + "platymuus.dm-langclient", + "stylemistake.auto-comment-blocks", + "eamodio.gitlens", + "oderwat.indent-rainbow", + "rexebin.darkpurple-black", + "dbaeumer.vscode-eslint", + "editorconfig.editorconfig", + "donkie.vscode-tgstation-test-adapter", + "icrawl.discord-vscode" + ] } diff --git a/guides/Guide to Your First POI Map.md b/guides/Guide to Your First POI Map.md new file mode 100644 index 0000000000..759ef04256 --- /dev/null +++ b/guides/Guide to Your First POI Map.md @@ -0,0 +1,155 @@ +Welcome! + +This guide **ASSUMES** you have gone through the Guide to Opening your First PR. If you have NOT done so yet, please refer here, and ask in Discord's #ss13-development channel (For CHOMPStation), #dev-general (for VOREStation), or #code (for Polaris) if you have any questions, or need assistance with completing these steps. + +You can also @ maintainers or staff devs, which can be viewed in the sidebar of each codebase’s Discord, and will usually have roles such as “Maintainer” (For VOREStation), “StaffDev/StaffMaintainer” (for CHOMPStation), and “Maintainer” (for Polaris). + +[CHOMPStation]([https://github.com/CHOMPStation2/CHOMPStation2/blob/master/guides/Guide%20to%20Opening%20Your%20First%20PR.md](https://github.com/CHOMPStation2/CHOMPStation2/blob/master/guides/Guide%20to%20Opening%20Your%20First%20PR.md)) + +[VOREStation]([https://github.com/VOREStation/VOREStation/blob/master/guides/Guide%20to%20Opening%20Your%20First%20PR.md](https://github.com/VOREStation/VOREStation/blob/master/guides/Guide%20to%20Opening%20Your%20First%20PR.md)) + +[Polaris - TBD] + +You will also WANT VSCode to edit the files, but this is not required, as DM can also do so. See Guide to VSCode/Editor Setup, or check the wiki pages on how to contribute to learn more. (These are currently TBD but will be done soon:™:) + +Before proceeding, remember to make your branch! We should have a new branch titled “x-dev-POI”, or whatever you want to name it. We’ll assume it’s named “shep-dev-POI” for this tutorial’s context. + +With that out of the way, congrats on getting setup! Let’s dive into how to make your first POI. \ + \ +To start, we need to open up the repo you downloaded earlier. If you’re not sure where that is, Gitkraken should be able to tell you by hovering over the codebase name, in the top left, and hitting **Alt+O** will open the file manager. \ +Either way, we should see [this]([https://i.imgur.com/FOUVK4n.png](https://i.imgur.com/FOUVK4n.png)) - Image references CHOMPStation, but the general folders should be the same for Polaris + VOREStation. + +Before we can map, we need to setup several code prerequisites in order to actually have a new area for our map. In order to do so, we are going to locate the POI folder. We are going to add a POI to the Wilderness area for our tutorial. + +Follow this reference: \ +Go to /maps/, and then find the folder the POIs for the given map are saved. This is code-base specific, so Polaris + CHOMP use /maps/submaps/surface_submaps/ for theirs, and then each folder (mountains, wilderness, plains) is a different area. If you’re on Southern Cross, Plains is the area around the outpost, Mountains is the mines, and Wilderness is the deep wilds. Polaris, TBD. + +VORE has their submaps for SPECIFIC areas defined in /mapused (IE Tether)/submaps. This sub-main folder should only be used for map-specific POIs, for example, POIs that would only exist if Tether was loaded. + +Otherwise, refer to /submaps/ and locate the folder in question. If you’re not sure, poke around, or ask in the channel for the codebase you’re currently working on for help. + +Once we’ve gotten to the folder in question, scroll down until you see, for this reference, wilderness.dm, and wilderness_areas.dm. + +Double click to open wilderness_areas.dm. Follow the subheadings depending on the tool you’re using. + +VSCode: If you’ve already installed VSCode and told it to associate with .dm files as per the tutorial, it’ll open here and error. We need to open the main folder, by going to File, Open Folder, and then navigate to our base repository. This is where all the folders like maps, guides, etc are. + +Hit Select Folder. We’ll open to a blank screen. Hit Ctrl + P to open a specific file, and type in wilderness_areas, and select wilderness_areas.dm. From here, refer to the joint section below. + +DreamMaker: This should have opened with our filetree, as screenshotted. [https://i.imgur.com/m8FjRAs.png](https://i.imgur.com/m8FjRAs.png) If it did not, navigate to File, Open Environment, and select vorestation.dme. Then, navigate to maps, submaps, surface submaps, wilderness, and open wilderness_areas.dm. + +Joint (This assumes we’ve located the file as per instructions above. If you’re not using Dream Maker or VSCode, you’re expected to understand how to open the file yourself.) This section will be done in VSCode, but later iterations will screenshot the process in Dream Maker (it’s basically identical, just waiting on the wiki page to bother doing so.) + +Go ahead and look over the areas. We’ll notice something, even if you don’t quite know how to read code: each new area only has name + ambience changed, likely, right? + +Image here [https://i.imgur.com/A2pMluj.png](https://i.imgur.com/A2pMluj.png) + +Without getting too deep into code, BYOND uses OOP, which in layman’s terms, means every single new object created with the same path as another will inherit things. This saves us having to redefine it every time we make a new one. + +For YOU this means all we’re going to do is highlight an area subsection (I’ll be using Black-Op Shuttle’s area for this) [https://i.imgur.com/zCUu0R3.png](https://i.imgur.com/zCUu0R3.png), hit copy, and then scroll down to the bottom, hit enter once to generate a new line, and hit paste. You should see this, if in VSCode: [https://i.imgur.com/AtQvNV6.png](https://i.imgur.com/AtQvNV6.png) + +Now we’re going to change “Blackshuttledown” to “myfirstPOI”. Change it to whatever you like, but I’m simply using a tutorial name here. Then, at the “name = “POI - blahblah”, we’re going to change it to “POI - Newbie”. Leave everything else alone for now unless you want a special ambience, though you can easily just replace AMBIENCE_HIGHSEC with AMBIENCE_OTHERWORLDLY. + +Once we’ve done that, our new area should look like this: [https://i.imgur.com/ttVNbYq.png](https://i.imgur.com/ttVNbYq.png) + +With that, we save, and exit the code. We’ll come back to it at a later step to ADD our POI to the actual map template section, but for now, we need to MAKE the POI first, no? + +For this next step, return to the BASE folder, where the .dme and maps/etc folders are. + + \ +We’re going to navigate to *tools* and then StrongDMM. This is not REQUIRED, but is heavily recommended - maintainers will ask you to run mapmerge where possible if you use DreamMaker. The rest of this guide WILL ASSUME YOU ARE USING STRONGDMM. The wiki will offer sections for DreamMaker as well as StrongDMM. \ + \ +Run sdmmlauncher.exe. Screenshot here: \ +[https://i.imgur.com/VxvRntf.png](https://i.imgur.com/VxvRntf.png) + +You should be greeted with this: [https://i.imgur.com/9dhRcz3.png](https://i.imgur.com/9dhRcz3.png) + +We are going to do something first before opening any environments. Go to File, Preferences in the top left. Then, in Interface Options, select a style you like. Rykka (hi, the author of this) uses Dark Coast. Use whatever you like. + +Under Save Options, **change this to TGM.** Check Sanitize Variables. Also check Clean Unused Keys, if this is not already checked. Nudge mode should be pixel_x/pixel_y. + +With that done, hit Open Environment, and navigate to the folder we downloaded in the earlier step. Open vorestation.dme, for VORE + CHOMP, or Polaris.dme for Polaris. + +The file will load, and then you’ll still be at a blank screen, but now the Environment Tree should have 4 directories under it. \ +This is what it looks like. [https://i.imgur.com/RtURzx8.png](https://i.imgur.com/RtURzx8.png) + +You should also be able to see the name in the top left. + +Now, we are going to go to File, New Map. \ +This will open a dialogue box with the base folder of our repo. Don’t panic. \ +Go to /maps/, and then find the folder the POIs for the given map are saved. This is code-base specific, so Polaris + CHOMP use /maps/submaps/surface_submaps/ for theirs, and then each folder (mountains, wilderness, plains) is a different area. If you’re on Southern Cross, Plains is the area around the outpost, Mountains is the mines, and Wilderness is the deep wilds. Polaris, TBD. + +VORE has their submaps for SPECIFIC areas defined in /mapused (IE Tether)/submaps. This sub-main folder should only be used for map-specific POIs, for example, POIs that would only exist if Tether was loaded. + +Otherwise, refer to /submaps/ and locate the folder in question. If you’re not sure, poke around, or ask in the channel for the codebase you’re currently working on for help. + +Once we’ve located the folder, we’ll assume we’re doing Wilderness for this one - we’ll be in this folder, and we’ll type the name of our new map and hit Save. Image here: [https://i.imgur.com/CCIuuwy.png](https://i.imgur.com/CCIuuwy.png) + +Now, it is going to bring up a dialogue box on map size. ALWAYS leave the Z at 1. \ +Set the X + Y to whatever you prefer, this will be the SIZE of our POI. For example, six tiles across would be 6 X, and 5 tiles tall would be 5 Y. The layout referenced in the tutorial is here: [https://i.imgur.com/T2jQwZB.png](https://i.imgur.com/T2jQwZB.png) + +Hit Ok. \ + \ +Your new map will load in the bottom-left corner, depending on SDMM. Scroll in using your mouse, and hold the middle mouse button (or whatever the hotkey is if SDMM ever changes) to pan. + +Once we’ve navigated and zoomed so our POI is relatively sized, we should see this: [https://i.imgur.com/e8VhPxk.png](https://i.imgur.com/e8VhPxk.png) + +Hit Save (Ctrl + S) now! Just in case. + +In the top left, where it says “Types Filter”, type the name of our new area. This will be “myfirstPOI”. Click to select. You should see this. [https://i.imgur.com/mG458sl.png](https://i.imgur.com/mG458sl.png) + +Go to the map editor, and drag it over the interior tiles. Then, go back to types filter (where we typed in prior), clear it, and find template. We’ll see two things come up, /turf/template_noop, and /area/template_noop. Do turf template around the outside of our new area, and then do area template around the outside of our new area. \ + \ +We should see this: \ +[https://i.imgur.com/z722p97.png](https://i.imgur.com/z722p97.png) + +Now go to Options, and hit “Toggle Area”. This will turn off the area display. Clear the types filter select, and hit the big - button next to it to collapse all trees again so we just have 4, these being (area/turf/obj/mob), our base BYOND types. + +Go to turf, then simulated, then floor, then outdoors, then dirt. Drag it over the center tiles, so now there should only be dirt + passthrough. (the template turf is also called passthrough in coder parlance). Obviously, we can add more turfs and get more complex if you like, but you’ll need to worry about atmos composition and etc. We’re not going to stress about that for now, as we can learn about all that later. + +For now, collapse all trees again, and then go to “mob”, then living, then simple_mob (do not use simple_animal, it is deprecated), then select a mob from any of these subtrees. For our example, we’re going to go to animal, wolf, direwolf, and choose a regular direwolf (or Rykka, if you’re on a VORE downstream). + +Place it anywhere on the dirt or passthrough tiles, and hit save. I recommend NOT placing on the passthrough tiles, as they may suddenly spawn inside solid rock. + +Make sure to save. We’ve accomplished adding a rudimentary, if not-super-featured POI. + +This is what it should look like before we close the editor. [https://i.imgur.com/MU1YuKs.png](https://i.imgur.com/MU1YuKs.png) + +Now, we’re going to go back to our editor of choice. Refer above for instructions on how to open the codebase on each editor, but we’re going to, instead of opening wilderness_areas, open wilderness.dm. + +This will bring you to a bunch of new stuff. You’re going to see an #if and etc. + +DON’T PANIC. + +All we’re going to do is scroll down the list, and find where our POI would slot in alphabetically. For instance, ours, via this tutorial, is myfirstPOI.dmm. We’re going to insert this after musk.dmm. + +Click at the end of #include “musk.dmm” and hit enter once, then type #include “myfirstPOI.dmm”. Name will vary, of course, depending on your POI, but for this tutorial, that’s the name we used. + +You should see this if the step was completed successfully. [https://i.imgur.com/c686Ji4.png](https://i.imgur.com/c686Ji4.png) + +Now, we’re going to scroll down. Remember earlier how it was explained that you only need to change the variables that DO change on your new map? + +Copy line 76, or this area snippet: `/datum/map_template/surface/wilderness/deep/BSD` + +At the end of the file, hit paste after inserting a new line underneath the last entry, so there’s always a line of space between the end of one thing and the next. + +Then, as with adding the area, change the “BSD” to your name, then “name = “blah”” to whatever your name is. + +Change the name of the .dmm in mappath to match your .dmm, and change the cost down to 5 (this is a very tiny POI). Remove the template_group, as we don’t use it presently. + +It should look like this afterwards: + +[https://i.imgur.com/HguoHxT.png](https://i.imgur.com/HguoHxT.png) + +And we’ve added it! Woo! + +Before you go “man that was way too much work fuck this” we still need to PR it. \ +Open your git client of choice - if you’ve been following the guide up to this point, we’ll reference Gitkraken. + +As explained in the Guide to Opening your First PR, you’ll need to Stage + Commit these files. If you’ve followed instructions and still need help, contact maintainers or ask for help in the development channels. + +Commit, and then again, as per prior, we are going to start a pull request. At this point, you should be done! + +As with the other guides, if you run into issues, please let maintainers know and we’ll help you out. DON’T FEEL BAD FOR BEING NEW AND GOING “AAA”. \ + \ +We all started somewhere. I hope this guide helps give you the confidence you need to contribute to this codebase and help keep our project going. Thank you for your time and effort. <3 \ No newline at end of file diff --git a/guides/Overmap Ships and Places - What's Needed.md b/guides/Overmap Ships and Places - What's Needed.md new file mode 100644 index 0000000000..f5795f0cbf --- /dev/null +++ b/guides/Overmap Ships and Places - What's Needed.md @@ -0,0 +1,59 @@ +Overmap Ships + Places, the Guide +This is a very basic list of just "what is needed". It is assumed you'll lookup where these go. +Proper, full-length guide will be added later to here + the wiki. +For now, just use this as reference for what is needed for Overmap ships + locations. + +**CREATED IN-EDITOR:** +``` +/obj/effect/shuttle_landmark + var edits: + base_area: what area to replace the shuttle's area with when it's left + base_turf: what turf to replace the shuttle's location when it's left + landmark_tag: lowercase identifier. Used in current_location + name: the landmark's name. +``` + +**CREATED IN-CODE:** +```c +/area/shuttle/SHIPNAME + name = "\improper [Name]" // Just replace [Name] with whatever your want to name the ship + icon_state = "shuttlered" + requires_power = 1 // Or 0 if you don't want to have to power the ship yourself. +//Area should probably be placed in southern-cross-areas.dm but the rest can go into some file all together. + +/datum/shuttle/autodock/overmap/SHIPNAME + name = "[Name]" + warmup_time = 0 + current_location = "" // See CREATED IN-EDITOR + shuttle_area = /area/shuttle/SHIPNAME // See above area. Can also be list of multiple areas. + fuel_consumption = 1 // Typically defines how much fuel the shuttle uses per jump. 1-3 is reasonable, base it on size. + move_direction = NORTH / SOUTH / EAST / WEST + +/obj/effect/overmap/visitable/ship/landable/SHIPNAME + name = "[Name]" // Can be named whatever, best to keep it similar to actual ship name. + desc = "Some description goes here." + vessel_mass = 1000 // Some factor for speed. For reference, 1000 is fucking fast, 10000 is only fast when maxed on engines and very costly. + vessel_size = SHIP_SIZE_TINY / SHIP_SIZE_SMALL / SHIP_SIZE_LARGE + shuttle = "[Name]" // Direct reference to above shuttle. MUST be the same as name. + +/obj/machinery/computer/shuttle_control/explore/SHIPNAME + name = "short jump console" + shuttle_tag = "[Name]" // Direct reference to above shuttle. MUST be the same as name. + req_one_access = list(access_pilot) +``` + +**OVERMAP SHIP CREATION INSTRUCTIONS:** +Build your shuttle however you'd like, though it MUST have: +- Phoron cannister(s) hooked up to proper engines. /obj/machinery/atmospherics/unary/engine +- Engine Control. `/obj/machinery/computer/ship/engines` +- Helm Control. `/obj/machinery/computer/ship/helm` +- Fuel port, for short distance jumps and docking. `/obj/structure/fuel_port` +- Short jump console, defined in code earlier. `/obj/machinery/computer/shuttle_control/explore/SHIPNAME` +- A spawned in effect, defined in code earlier, inside of the ship area. `/obj/effect/overmap/visitable/ship/landable/SHIPNAME` +- A docking point, made through the map editor, mentioned earlier. `/obj/effect/ship_landmark`. Typically this is placed inside the ship, directly in front of the exterior door. This dictates where it places the shuttles so be sure to actually test how your shuttles react to landing in odd locations. The landmark's tag also needs to be added to the appropriate area in `maps/southern_cross/overmap/sectors.dm` or else ships cannot dock there. +- The shuttle also needs to be placed entirely in the designated area that you made in the above code, since shuttles are based off of the area everything is in. + +It would be **RECOMMENDED** to also have: +- Sensors, controlled by `/obj/machinery/computer/ship/sensors` and `/obj/machinery/shipsensors` (maybe the /weak variant for small ships if you add them at all?) +- Docking Controller. Not 100% sure on how these work yet, but will be updated as needed. Not necessary, just nice to have for ease of access. +- A pump somewhere in the fuel intake to your engines, for better fuel management. \ No newline at end of file diff --git a/guides/VSCode Setup Guide.md b/guides/VSCode Setup Guide.md new file mode 100644 index 0000000000..35f298b3c2 --- /dev/null +++ b/guides/VSCode Setup Guide.md @@ -0,0 +1,30 @@ +This guide will simply list VSCode + the extensions needed, plus very basic instructions, as VSCode has a NUMBER of tutorials on it, and there's little need to reinvent the wheel. +It is assumed that you can follow the VSCode walkthrough. Navigate to the Extensions tab on the left, type @recommended, and then install each extension under the "Recommended" Tab. +Screenshot here, but don't rely on this as the workspace recommendations may change over time. https://i.imgur.com/CF0P6TI.png +If you require assistance, don't feel stupid! Just ask a maintainer or ask in Discord for help. Be prepared to take screenshots if you need. + +**VSCode + All mission-critical extensions for DM Coding.** + VSCode, the root tool. + DM language support, allow autoupdates + DM Language client, also allows compiling. When setting it up you need to go to extension settings, then "choose folder", pick the BYOND folder that has "uninstall.exe" and "bin" folders (the root/base folder). Then, once that's done, you can literally hit ctrl+shift+b and choose the .dme, and compile inside VSCode. It's FAR faster than compiling in Dream Maker. +Screenshot of settings: + Auto Comment Blocks (Allows multi-line comments easily in DM) + Indent Rainbow - makes your indents colorcoded by how deep they are. + Not adapted for our code yet, but this allows one to run compile tests the same as online does. + +{ +"editor.bracketPairColorization.enabled": true, +"editor.guides.bracketPairs":"active" +} + +Add this to settings.json +If you run into issues, ask in Discord for help. + +**Optional.** + Discord rich presence, not needed, but looks pretty + This one is also optional, works for allowing you to gitblame and stuff. Requires setup, but will walk you through it, and ALSO links with Gitkraken. Extremely handy. + +**Quick Tips for VSCode** +Highlighting a proc and right clicking, then going to "Definition" or "Implementation" will allow you to easily see/lookup wherever it's used. This is massively helpful over having to manually search it. +CTRL+F will bring up a search, that also allows a replace line-by-line. +CTRL+Clicking will also (usually) take you to the definition of a proc/verb/etc. \ No newline at end of file