Skip to content

Custom Weapons

Jump to bottom Edit New page
Cong edited this page Oct 17, 2016 · 12 revisions

C-Dogs SDL lets you create custom weapons for campaigns and dogfights. You can do this by defining your own guns and bullets, and optionally providing your own graphics and sounds. All the weapons in C-Dogs are implemented using the same system!

There are two key concepts: guns fire bullets, and bullets travel and hit things. But did you know that bullets can also fire guns? This is how grenades work: when the grenade "bullets" reach the end of their range, they "fire" an "explosion gun", which in turn fires "explosion fireballs". Of course it doesn't have to end there...

Getting started? Try the walkthrough

Reference

Here's a big list of properties that you can set for guns and bullets:

guns.json Most fields are optional; if omitted, their values come from the "defaultGun" definition in the game's guns.json.

  • Pic (string): what the player will hold. Values: "knife", "blaster" or "".

  • Name (string, required): what the gun will be called, in menus and in the HUD. Must be unique!

  • Bullet (string): the name of the bullet that the gun will fire. Check out /data/bullets.json, or if you're using custom bullets, make sure to provide one with this name in your bullets.json.

  • Cost (integer): how much the gun costs to fire, in terms of score. Most guns in C-Dogs costs score to fire.

  • Lock (integer): rate of fire, in terms of the number of game ticks between each bullet fired. The number of ticks per second is 70, so a lock of 70 is one shot per second, 7 is 10 shots per second.

  • ReloadLead (integer): when the reload sound is played, ahead of when the gun is able to be fired again, in terms of game ticks. For guns that take a long time to reload, it's a good idea to add a reload sound to let the player know when they can fire again. It's best to have the sound play a little before the gun is actually ready, hence this parameter. Great for shotguns, rifles etc.

  • Sound (string): what sound this gun makes when fired. Must be a sound that is in /sounds, or provide your own in your /sounds folder. Skip the extension!

  • ReloadSound (string): what sound to play when this gun becomes ready to fire. If you want to play the sound before the gun is ready, set a value for ReloadLead.

  • SoundLockLength (integer): time between the gun making its sounds, in game ticks. Sometimes you want to have a rapid-fire gun but it would sound awful if it made a sound every shot! Set a SoundLockLength value to space out the firing sounds. Great for flamers, or anything that fires a continuous stream.

  • Recoil (float): the random spread of the bullets, in radians.

  • SpreadCount (integer): for guns that fire a spread of bullets, how many bullets to fire. Great for shotguns.

  • SpreadWidth (float): the angle between each bullet in a spread, in radians.

  • AngleOffset (float): normally guns fire bullets in whatever direction the player is facing; if you want to fire slightly to the left or right, use a value for this (in radians). Mainly used for explosions, to slightly rotate the spread pattern.

  • MuzzleHeight (integer): how high the bullet will be fired at. Default is 10, which matches the gun the player is holding. If you want a bullet to come out at the player's feet (think dynamites, mines), use 0.

  • Elevation, or ElevationLow and ElevationHigh (integer): whether the bullet will be fired at an angle up or down. Positive means the bullet will travel upwards. Values are in 1/16th pixels. You can either use a single Elevation value, or provide both ElevationLow and ElevationHigh - the game will randomly choose values within that range every time the gun fires. Great for explosions and grenades when coupled with the bullet's Falling property. Note: C-Dogs is a 2D game and bullet height has no effect on whether it will hit or not, it's mostly cosmetic! (but it does affect when the bullet hits the ground...)

  • MuzzleFlashParticle (string): the name of the particle that represents the muzzle flash. The particle must already exist in /data/particles.json, or provide your own in your particles.json. See particles.json for more details.

  • Brass (string): the name of the particle that represents ejected casings / brass. These are small particles that fly out from the side of the gun, and typically land on the ground. Great for machine guns!

  • CanShoot (boolean): whether you can fire this gun. "How can you possibly not fire a gun???" the answer is: the knife. This is only used for the knife.

  • ShakeAmount (integer): when the gun is fired, how much the screen will shake. Don't over-do this! Great for explosions, or very big guns.

bullets.json

  • Name (string, required): unique bullet name, referred to by the guns.

  • Pic (object): describes the pictures used to draw this bullet. It has the following fields:

    • Type (string): picture type; can be "Normal", "Directional", "Animated" or "AnimatedRandom"
    • (If Type is Normal): this means a single image is used. Include the following field:
      • Pic (string): name of image file (without extension)
    • (If Type is Directional): this means a "directional" spritesheet image is used. The spritesheet must have 8 sprites, each representing a different direction, starting from up and continuing clockwise. Include the following field:
      • Sprites (string): name of the spritesheet image file (without extension or dimensions). Note that spritesheet image files have filenames of the following form: name_wxh.ext. Specify only name for this spritesheet.
    • (If Type is Animated or AnimatedRandom): this means a spritesheet representing an animation is used. For AnimatedRandom, the frames are selected at random - good for flame animations. Include the following fields:
      • Count (integer): start the animation before or after a number of ticks. If positive, the animation starts a number of ticks ahead. If negative, the animation does not start until a number of ticks has passed. Mainly used if you want to use an animation, but to have it start in the middle, or not to start until some time has passed.
      • TicksPerFrame (integer): the frame rate of the animation, in terms of number of ticks per frame. The game uses 70FPS by default, so a TicksPerFrame of 2 means 35FPS.
    • Either one of:
      • Mask (hexadecimal string): represents a color to blend with the bullet pictures via multiplication. To represent red, use the string "ff0000". Note: for best results, use a grayscale picture.
      • Tint (array of floats length 3): represents a HSV. The picture is only used as a mask, and the tint is applied over the existing draw buffer. Good for smoke and transparency effects.

  • ShadowSize (array of integers length 2): represents width and height of a blob shadow. The shadow is only drawn if the bullet is off the ground. Great for grenades, to show how far off the ground the grenade is.

  • Delay (integer): number of ticks to delay updating this bullet - includes moving and collision. This value is typically the negative of Pic.Count so that delayed bullets aren't drawn until a certain time after the gun was fired.

  • Speed, or SpeedLow and SpeedHigh (integer): bullet speed, in terms of 1/256th pixels travelled per tick. That is, a Speed of 256 means the bullet will travel 1 pixel per tick. If SpeedLow/SpeedHigh are used, the game will randomly choose a speed within this range for each bullet.

  • SpeedScale (boolean): whether to scale the vertical speed to match the tile perspective. C-Dogs uses a slightly inclined top-down perspective: tiles are 16x12, or a 4:3 ratio. Setting SpeedScale to true will mean that the bullet's vertical speed is scaled to be 3/4 of its normal speed. Good for explosions, where the shape will be noticeable.

  • Friction (integer): how much the bullet will slow down by, in terms of 1/256th pixels. Note: the "friction" will continue to apply after the bullet has stopped! Hint: use negative friction for acceleration.

  • Range, or RangeLow and RangeHigh (integer): number of ticks the bullet will stay alive for (if not destroyed by collisions). To calculate the actual range of the bullet, multiply Range by Speed.

  • Power (integer): amount of damage the bullet will cause on collision. Note: bullets that don't disappear after collisions will keep dealing this much damage, as long as the player is overlapping with the bullet.

  • Mass (float): affects push-back when hitting a target character. Note: push-back also scales by speed. Hint: mass can also be negative, which causes the target to be pulled towards the shooter...

  • Size (array of integers length 2): width and height of bullet; affects collisions.

  • Special (string): if the bullet's damage has special properties. Can be "Flame" (target turns red), "Poison" (target turns green and starts taking poison damage), "Petrify" (target turns gray and freezes), or "Confuse" (target turns purple and has their directions reversed).

  • HurtAlways (boolean): whether the bullet hurts all players, even friendly players. Good for explosions and other "dangerous" weapons, but be careful - players don't like team kills!

  • Persists (boolean): whether the bullet stays alive even after hitting players and objects. Good for fireballs and gas clouds.

  • Spark (string): the name of the particle that will be drawn when the bullet hits things. Check out /data/particles.json, or if you're using custom bullets, make sure to provide one with this name in your particles.json.

  • HitSounds (object): specifies sounds to play when the bullet hits various items. Use the filename of the sound, without the file extension. Check out /sounds, or if you're using custom sounds, make sure to provide one with this name in your /sounds folder. Using different sounds for different hits is recommended as it gives useful feedback to players. It has the following fields:

    • Object (string): when the bullet hits in-game objects like crates and barrels.
    • Flesh (string): when the bullet hits players.
    • Wall (string): when the bullet hits walls.

  • WallBounces (boolean): whether the bullet bounces off walls, instead of being destroyed.

  • HitsObjects (boolean): whether the bullet can hit objects, or go through them.

  • Falling (object): properties that control whether the bullet falls as if by gravity, and falling-related properties such as bouncing. It has the following fields:

    • GravityFactor (integer): multiplication factor for gravity. 1 is normal gravity. Higher values means the bullet will fall quicker.
    • FallsDown (boolean): whether the bullet is allowed to fall downwards. If false, bullet may still be affected by gravity, but it can only slow its ascent.
    • DestroyOnDrop (boolean): whether the bullet is destroyed as soon as it hits the ground.
    • Bounces (boolean): whether the bullet bounces up off the ground. If false, the bullet will stay on the ground after it lands.
    • DropGuns (array of gun names): the guns to fire when this bullet drops to the ground. Hint: used by molotov.

  • SeekFactor (integer): enables heat-seeking, using a division factor. Higher values means the bullet will seek with less speed.

  • Erratic (boolean): whether the bullet flies around randomly. Only used for the browny gun.

  • OutOfRangeGuns (array of gun names): the guns to fire when this bullet goes out of range, i.e. reaches end of life. Good for grenades.

  • HitGuns (array of gun names): the guns to fire when this bullet hits something - player, object or wall.

  • ProximityGuns (array of gun names): the guns to fire when any player comes within 1 tile distance of the bullet. Used for the proximity mine.

Sample

The techdemo/funwithguns.cdogscpn campaign contains several custom weapons, including custom graphics and sound. You can use it as a handy template.

Add a custom footer
Add a custom sidebar
Clone this wiki locally