diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9cb3c51..4b00b06 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,10 +1,26 @@ ## PR Summary -[ REPLACE this with a DETAILED SUMMARY of your changes ] +## Changed all C# mentions of arrays to be Lua-friendly **site-wide** +## ex: before, it would mention arrays of instances as Instance[], but now it will mention them as {Instance}. This is so that lua programmers know what they're looking at, and so that we can fit multiple class names as needed. -Thanks for taking the time to contribute to the Polytoria documentation project! -Please ensure that this PR meets the following criteria before submitting (you may delete this section after reading): +## Edited Camera.md to change the "Freecam" typo to "FreeCam" +## Added warning about lua's single-thread nature in BaseScript.md, and how to work around it -- [ ] The changes you've made are accurate and correct -- [ ] Distinct changes for separate issues are in separate PRs (do not combine multiple issues into one PR) -- [ ] Any additions or modifications to the example code were tested in the latest version of Polytoria Creator and work as intended +## Environment.md changes: +## Added links to nearly every reference of objects in the entire file +## Added optional parameter markers for CreateExplosion +## Modified CreateExplosion note to be more in depth and specific with wording +## Added optional parameter marker for OverlapBox and OverlapSphere +## Completely rewrote the Raycast and RaycastAll methods to be more comprehensive +## Remade RebuildNavMesh documentation :sob: :pray:, please tell me I'm not the only one that laughed when I saw game["Workspace"] +## Added optional parameter marker for GetPointOnNavMesh +## Rewrote AutoGenerateNavMesh documentation to be more comprehensive +## Added more details to PartDestroyHeight's behavior with NPCs and Players + +## Added extensive explanation as to how RayResult.Normal works in RayResult.md + +## Added warning about GUI.Visible behavior in GUI.md + +## Added warning about Tool-descendant scripts and their odd inability to run until the first Tool.Equipped event in Tool.md + +## merged with the latest pull request (all they did was organize the layout in creator-setup.md :sob:) \ No newline at end of file diff --git a/docs/assets/tree/Purchases.png b/docs/assets/tree/Purchases.png new file mode 100644 index 0000000..962a4d4 Binary files /dev/null and b/docs/assets/tree/Purchases.png differ diff --git a/docs/objects/game/Camera.md b/docs/objects/game/Camera.md index 0ee305d..5865f5c 100644 --- a/docs/objects/game/Camera.md +++ b/docs/objects/game/Camera.md @@ -133,7 +133,7 @@ Camera.MinDistance = 5 ### Mode:CameraMode { property } -Determines or returns the camera's current mode `(Scripted, FollowPlayer, Freecam)`. +Determines or returns the camera's current mode `(Scripted, FollowPlayer, FreeCam)`. **Example** diff --git a/docs/objects/game/Environment.md b/docs/objects/game/Environment.md index e229b89..ada91de 100644 --- a/docs/objects/game/Environment.md +++ b/docs/objects/game/Environment.md @@ -17,9 +17,9 @@ weight: 2 ## Methods -### CreateExplosion(Position;Vector3,Radius;float=10,Force;float=5000,affectAnchored;bool=true,callback;function=nil,damage;float=10000) { method } +### CreateExplosion(Position;Vector3,?Radius;float=10,?Force;float=5000,?affectAnchored;bool=true,?callback;function=DynamicInstance,?damage;float=10000) { method } -Creates a deadly explosion killing players and applying force to parts at the given position. +Creates a deadly explosion killing {{ classLink("Players") }} and applying force to {{ classLink("DynamicInstance") }}s at the given position. **Example** @@ -28,16 +28,14 @@ game["Environment"]:CreateExplosion(Vector3.New(0, 0, 0), 30, 5000, false, nil, ```
-!!! note "When set to true, AffectAnchored will unanchor parts within the explosion radius." -
+!!! note "When set to true, AffectAnchored will disable the Anchor property for {{ classLink("DynamicInstance") }}s within the explosion radius." -
-!!! note "Callback gets called for each part within explosion radius." +!!! note "Callback gets called for each {{ classLink("DynamicInstance") }} within explosion radius."
-### OverlapBox(position;Vector3,size;Vector3,rotation;Vector3,ignoreList;array=Instance[]):Instance[] { method } +### OverlapBox(position;Vector3,size;Vector3,rotation;Vector3,?ignoreList;array={Instance}):{Instance} { method } -Returns a list of instances intersecting with the box in the given position, size and rotation. +Returns a list of {{ classLink("DynamicInstance") }}s intersecting with the box in the given position, size and rotation. A demo of this method is available [here](https://polytoria.com/places/9269). @@ -51,61 +49,77 @@ for i,v in ipairs(intersections) do end ``` -### OverlapSphere(position;Vector3,radius;float,ignoreList;array=Instance[]):Instance[] { method } +### OverlapSphere(position;Vector3,radius;float,?ignoreList;array={Instance}):{Instance} { method } -Returns a list of instances intersecting with the sphere in the given position and radius. +Returns a list of {{ classLink("DynamicInstance") }}s intersecting with the sphere in the given position and radius. **Example** ```lua -local intersections = game["Environment"]:OverlapSphere(Vector3.New(100,0,45), 25) +local intersections = game["Environment"]:OverlapSphere(Vector3.New(100,0,45), 25, {game["Environment"]["TheIgnored"]}) for i,v in ipairs(intersections) do print(v.Name .." is intersecting the sphere!") end ``` -### Raycast(origin;Vector3,direction;Vector3,maxDistance;float=infinite,ignoreList;array=Instance[]):RayResult { method } +### Raycast(origin;Vector3,direction;Vector3,?maxDistance;float=infinite,?ignoreList;array={Instance}):RayResult { method } -Casts a ray from origin with a specified direction and returns a RayResult for the first hit object. +Casts a ray from origin, shooting in the direction of the second argument until it reaches the distance threshold, only stopping upon reaching a {{ classLink("DynamicInstance") }} that isn't nested in ignoreList. **Example** ```lua -local hit = game["Environment"]:Raycast(barrel.Position, barrel.Forward) - -if hit and hit.Instance:IsA("Player") then - hit.Instance.Health = 0 +local Ray = game["Environment"]:Raycast(barrel.Position, barrel.Forward, 25, {game["Environment"]["IgnoredInstances"], game["Environment"]["OtherIgnoredInstances"]}) + +if Ray ~= nil then + local Hit = Ray.Instance -- Player + if Hit:IsA("Player") then + print("Hit",Hit,"at",Ray.Position,"!") -- [Hit Player at (3.24, 1.2, 5.93) !] + Hit.Health = math.max(Hit.Health - 12 * (1.5-(1- Ray.Distance / 25)), 0) + --Point blank deals 18 damage while max distance deals 6 damage + end end ``` -### RaycastAll(origin;Vector3,direction;Vector3,maxDistance;float=infinite,ignoreList;array=Instance[]):RayResult[] { method } +
+!!! tip "The descendants of an {{ classLink("Instance") }} in ignoreList are ignored too." +!!! warning "If the Raycast fails to hit a {{ classLink("DynamicInstance") }}, it is returned as nil." +
+ +### RaycastAll(origin;Vector3,direction;Vector3,?maxDistance;float=infinite,?ignoreList;array={Instance}):{RayResult} { method } -Casts a ray from origin with a specified direction and returns a RayResult array for all hit objects. +Casts a ray from origin, shooting in the given direction until it reaches the distance threshold, only returning a table of {{ classLink("DynamicInstance") }}s that aren't nested within the ignoreList. **Example** ```lua -local hits = game["Environment"]:RaycastAll(Vector3.New(0, 10, 0), Vector3.New(0, -1, 0), 100) - -for i, hit in pairs(hits) do - print("Hit at " .. hit.Position .. "!") +local Ray = game["Environment"]:RaycastAll(Vector3.New(0, 10, 0), Vector3.New(0, -1, 0), 100, game["Environment"]["Map"]) + +--We call this the Railgun. +for i, hit in pairs(Ray) do + if hit.Instance:IsA("NPC") then + if hit.Position.y - hit.Instance.Position.y >= hit.Instance.Size.y then + hit.Instance.Health = 0 --An accurate headshot detection, no matter the size of the NPC + --(hit.Instance.Position.y + hit.instance.Size.y == where the NPC's neck is on the y scale) + else + hit.Instance.Health = math.max(0, hit.Instance.Health - 50) --Body shot + end + end end ``` -### RebuildNavMesh(root;Instance=nil) { method } +### RebuildNavMesh(?root;Instance) { method } -Rebuilds the navigation mesh which determines the empty space where NPCs can pathfind in. +Rebuilds the navigation mesh which determines the empty space where {{ classLink("NPC") }}s can pathfind in. **Example** ```lua -game["Environment"]:RebuildNavMesh() -# or -game["Environment"]:RebuildNavMesh(game["Workspace"]["Map"]) +game["Environment"]:RebuildNavMesh(game["Environment"]["Map"]) ``` -### GetPointOnNavMesh(position;Vector3,maxDistance;float=infinite):Vector3 { method } +### GetPointOnNavMesh(position;Vector3,?maxDistance;float=infinite):Vector3 { method } Returns a point on the navigation mesh at the given position. @@ -113,10 +127,10 @@ Returns a point on the navigation mesh at the given position. ### AutoGenerateNavMesh:bool { property } -Determines whether or not to automatically build a navigation mesh for NPC pathfinding. This property is disabled by default so there are no performance issues with larger maps. +Determines whether or not to automatically build a navigation mesh from :polytoria-Environment: Environment for {{ classLink("NPC") }} pathfinding. This property is disabled by default so there are no performance issues with larger maps.
-!!! note "When updating the map, even if the property is set to true, you will still have to manually call the `Environment:BuildNavMesh()` method." +!!! warning "AutoGenerateNavMesh only runs once upon being set to true. Changing the map will still require you to run RebuildNavMesh."
### FogColor:Color { property } @@ -137,11 +151,11 @@ Whether or not fog is enabled. ### FogStartDistance:float { property } -The distance from the camera at which fog starts to appear +The distance from the {{ classLink("Camera") }} at which fog starts to appear ### FogEndDistance:float { property } -The distance from the camera at which fog is fully opaque +The distance from the {{ classLink("Camera") }} at which fog is fully opaque ### Gravity:Vector3=Vector3.New(0, -75, 0) { property } @@ -157,6 +171,11 @@ The height at which unanchored parts are destroyed when they fall below it. game["Environment"].PartDestroyHeight = -2000 ``` +
+!!! note "PartDestroyHeight only kills {{ classLink("Players") }}, and destroys {{ classLink("DynamicInstance") }}s with Anchor set to false." +!!! warning "PartDestroyHeight may kill {{ classLink("Players") }}, but it does not kill {{ classLink("NPC") }}s." +
+ ### Skybox:SkyboxPreset { property } The default skybox preset to use for the world, if no ImageSky is present. diff --git a/docs/objects/scripting/BaseScript.md b/docs/objects/scripting/BaseScript.md index 0173290..fbb5a6a 100644 --- a/docs/objects/scripting/BaseScript.md +++ b/docs/objects/scripting/BaseScript.md @@ -29,5 +29,7 @@ game["ScriptService"]["Script"]:Call("Foo", "Bar") ```
+!!! tip "Scripts are naturally single-threaded, but can run multiple threads at once through Signals and :Call." + !!! failure "Local Functions cannot be ran using the Call function." -
+ \ No newline at end of file diff --git a/docs/objects/static-classes/Purchases.md b/docs/objects/static-classes/Purchases.md new file mode 100644 index 0000000..4c8294b --- /dev/null +++ b/docs/objects/static-classes/Purchases.md @@ -0,0 +1,40 @@ +--- +title: Purchases +description: Purchases is a static class, that is used to prompt purchases to a player. +icon: polytoria/Purchases +--- + +# Purchases + +{{ staticclass("Purchases") }} + +{{ serverexclusive() }} + +:polytoria-Purchases: Purchases is a static class, that is used to prompt purchases to a player. + +
+!!! note "Purchases is not fully documented yet, and may receive changes." +
+ +## Methods + +### Prompt(player;Player,itemID;int,callback;function):callback { method } + +Prompts the specified player the specified item. + +**Example** + +```lua +game["Players"].PlayerAdded:Connect(function(plr) + wait(2) + Purchases:Prompt(plr, 86803, function(success, error) + if success then + print("Thank you for your purchase!") + else + print("Something went wrong with your purchase: " .. error) + end + end) +end) +``` + +The callback function has the parameter "success", indicating if the prompt was purchased, declined, or an error occurred. The callback function's "error" parameter contains the error message if the prompt failed. \ No newline at end of file diff --git a/docs/objects/system/Instance.md b/docs/objects/system/Instance.md index 783f30e..b2965b4 100644 --- a/docs/objects/system/Instance.md +++ b/docs/objects/system/Instance.md @@ -165,11 +165,11 @@ Attempts to find the first child instance with the specified name (`nil` if not Attempts to find the first child instance with the specified class (`nil` if not found). -### GetChildren:Instance[] { method } +### GetChildren:{Instance} { method } Returns an array of all the children instances parented to the instance. -### GetChildrenOfClass(className;string):Instance[] { method } +### GetChildrenOfClass(className;string):{Instance} { method } Returns an array of all the children instances with the specified class. diff --git a/docs/objects/types/RayResult.md b/docs/objects/types/RayResult.md index a31d018..28924ec 100644 --- a/docs/objects/types/RayResult.md +++ b/docs/objects/types/RayResult.md @@ -16,3 +16,10 @@ icon: polytoria/RayResult | `Vector3` Position | The position the ray made contact at. | | `float` Distance | The distance between the hit and origin. | | `Vector3` Normal | The normal of the surface the ray hit. | + +
+!!! tip "Don't understand Normal?" + + Normal is a naturally complicated property to describe. In a simple case of a cube, Normal describes the exact side the RayResult hit, with x being left/right, y being top/bottom, and z being front/back. + For a more complicated hitbox like a Sphere, the values can blend together. It's important to remember that the Instance's Rotation should be considered when making calculations with Normal. +
\ No newline at end of file diff --git a/docs/objects/ui/GUI.md b/docs/objects/ui/GUI.md index a39c54d..83da586 100644 --- a/docs/objects/ui/GUI.md +++ b/docs/objects/ui/GUI.md @@ -19,3 +19,7 @@ Determines whether the GUI is visible or not. ```lua gui.Visible = true ``` + +
+!!! warning "The Visible property will be automatically set to true when launching the client." +
\ No newline at end of file diff --git a/docs/objects/world/MeshPart.md b/docs/objects/world/MeshPart.md index df5474b..d2c30b7 100644 --- a/docs/objects/world/MeshPart.md +++ b/docs/objects/world/MeshPart.md @@ -34,9 +34,9 @@ Stops playing the current animation. Returns the names of the animations associated with the mesh. -### GetAnimationSources:string[] { method } +### GetAnimationSources:{string} { method } -### GetAnimationInfo:AnimationInfo[] { method } +### GetAnimationInfo:{AnimationInfo} { method } ## Properties diff --git a/docs/objects/world/Tool.md b/docs/objects/world/Tool.md index 49a4037..94592e0 100644 --- a/docs/objects/world/Tool.md +++ b/docs/objects/world/Tool.md @@ -12,6 +12,10 @@ weight: 7 {{ inherits("DynamicInstance") }} +
+!!! warning "{{ classLink("BaseScript") }}s that are descendants of Tools won't run until after the Tool's first Equipped Event." +
+ ## Events ### Activated { event } diff --git a/docs/theme/.icons/polytoria/Purchases.svg b/docs/theme/.icons/polytoria/Purchases.svg new file mode 100644 index 0000000..edb9280 --- /dev/null +++ b/docs/theme/.icons/polytoria/Purchases.svg @@ -0,0 +1,6 @@ + + + + + + \ No newline at end of file